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INTRODUCTION 


At this point the bookshelves have many books about OS/2, from general 
introductions to advanced programming techniques. As the product is 
maturing the need for more specialized books on OS/2 has developed. This 
book addresses solely the topic of device drivers. A "device driver" is a 
program that runs as part of the operating system and provides the 
programmer with the most powerful tool available for extension of the 
operating system. Device drivers are written at the system level and are 
unique in their execution in that they are integrated into the kernel itself. 

A thorough understanding of OS/2 internals must include the study of 
this complex subject, which cannot be treated properly in a single chapter 
of a more comprehensive text. In fact, several interesting topics had to be 
excised in order to limit the scope of this text to the main structural 
concepts. In short, device drivers are a window into OS/2 through which 
the greatest insight into the concepts of this modem operating system 
may be gained. 

I have attempted to write a book accessible to those who need the 
programming power of device drivers, and to those who wish to under¬ 
stand OS/2 more completely. I have identified and addressed three 
audiences: the DOS or OS/2 application programmer who wants to learn 
more about how OS/2 functions, systems programmers who have no OS/2 
experience, and OS/2 systems programmers. 

The application programmer is expected to have some familiarity with 
the 80286 assembler. Assembler was chosen as the language for this book 
because it most naturally expresses the hardware concepts involved. Once 
the concepts are mastered, drivers may be written in C with the use of a 
C language interface at some cost in efficiency. 


xv 
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Systems programmers will find a clear, yet detailed, picture of the 
programming concepts, calculated to eliminate any preconceptions from 
other systems programming environments, and generally to s im plify 
migration to the OS/2 environment. 

Finally, the OS/2 systems programmer will find a detailed reference 
section including all exceptional behavior and appendices organized for 
quick reference. Detailed, practical examples are included with explana¬ 
tions to illustrate every area of concern. 

I welcome any comments, questions, or suggestions for future editions 
via MCI Mail (user name FUTURE WARE). 

Raymond Westwater 

July, 1989 



CHAPTER 1 


AN OVERVIEW OF DEVICE DRIVERS 


A device driver is a piece of software that provides a window into the 
operating system. Its function is to operate a device controller which, in 
turn, operates a physical device. By their nature, device drivers are close 
to the hardware and to the operating system’s internals. This three-way 
marriage among hardware, driver, and operating system provides the 
driver with the power necessary to receive operating system commands, 
communicate device data to a task running under the operating system, 
modify operating system structures to reflect device state, and communi¬ 
cate and synchronize with the device. 

The device driver’s function is by no means limited to physical device 
control. Due to its low-level interface to the operating system, the driver 
may be viewed as having extended functionality. Examples of device 
driver-provided functional extensions to the operating system are by no 
means limited to the following examples: 

• Operating system threads of execution access a driver at a single 
entry point, allowing a driver to be a "clearinghouse" to tasks. 

• The driver can allocate memory, map memory, and share memory 
among tasks in varied ways. 

• Drivers can access, distribute, and alter operating system informa¬ 
tion (although Microsoft strongly discourages this use). 


1 
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The device driver may also be viewed as a teaching tool, as it provides 
access to the operating system and to the underlying hardware. The 
device driver is a powerful probe for exploration of the internal machina¬ 
tions of the operating system and the operation of any hardware. Learn¬ 
ing how to write device drivers will give driver writers great insight into 
the operating system and will place in their hands the most powerful 
low-level operating system functional extension tool available. 

With power comes responsibility! The device driver is difficult to write 
correctly, and subtle errors may not surface for months. The operating 
system has no protection against the device driver, and the smallest bug 
may have disastrous and unpredictable effects on any portion of the 
system. The need for careful design and thorough debugging cannot be 
overstated. 

1.1 Hardware Overview 

A device driver writer’s responsibility is to interface a device controller to 
the OS/2 operating system. The driver must understand how the device 
controller operates the hardware and must be able to format device 
controller commands and interpret device controller status information. 

Certain aspects of the controller interface are specified by the processor 
hardware and additional aspects are defined by the conventions estab¬ 
lished in the AT and PS/2 families of machines. It is imperative that the 
driver writer have some familiarity with these topics. 

The means by which certain OS/2 features are implemented and the 
apparent strengths and limitations of those features, are often derived 
from the nature of the processor hardware. Understanding this hardware 
is crucial for the proper conception and implementation of OS/2 device 
drivers. 


1.1.1 Device Control 

The interface between the device controller and the device driver has 
several components. First is the means by which the device controller is 
operated by the device driver. The device controller is addressable by 
either an I/O port or a memory-mapped address (see Figure 1-1). 
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The OUT instruction writes data to an I/O port address and the IN 
ins truction is used to read from an I/O port, typically to read device status 
information or to transfer a single byte of data. When the device driver 
receives a command packet from the operating system, the driver usually 
will write cert ain device control information and then (in case of a WRITE 
packet) write a byte of data to start the transfer. The driver will then wait 
for the device to request coordination to process the next byte (interrupt 
operation), or perhaps sleep for a fixed period of time and then test the 
controller status to determine if the device is ready to process an addi¬ 
tional character (polled operation). I/O ports are not relocated or 
processed by the processor hardware and polled operations may actually 
take place at the task level; they do not necessarily require development 
of a device driver. 


Figure 1-1: Hardware Level Device Control 


Device 

80286 Controller 
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A memory-mapped address must be accessed by a device driver. The 
80286 hardware provides virtual addressing and protects the contents of 
one address space from all other spaces. In particular, all hardware 
addresses are protected from all tasks. This means only a device driver 
can access these addresses. 

The memory-mapped address of the device controller is converted by 
the device driver into a selector:offset address which may then be used in 
a processor instruction to read or write device control registers. Amemory- 
mapped controller can function in polled operation mode as described 
above, but interrupt-driven operation is far more common. This is at least 
partially due to the fact that polled device operation may be supported at 
the task level in the case of I/O port-mapped device controllers, but 
memory-mapped device controllers require a device driver for their opera¬ 
tion. As we will see shortly, interrupt-driven operation also requires a 
device diiver. 

Some device controllers also support Direct Memory Access (DMA) data 
transfer. This means of data communication allows for the transfer of 
multiple bytes with a single programming of the device controller 
registers. The 80286 hardware, in conjunction with hardware on the 
device controller, allows for the transfer of a number of consecutive bytes 
m memory to or from the device controller. As was the case with memory- 
mapped devices, only device drivers can address the physical memory 
region that will be used to buffer the data transfer. These devices are also 
typically interrupt-driven. 

1.1.2 Interrupt Hardware 

An interrupt is both a signal from the device controller that an I/O 
operation is complete and a request for action from the device driver. 
Hardware support for interrupts is provided on the 80286 chip. 

The sequence of events surrounding an interrupt is created by the 
interaction between the processor, the interrupt support chip (PIC), and 
the device controller; and must be synchronized with software written to 
interpret the interrupt request. The OS/2 model of interrupt handling 
hides much of the hardware sequence from the driver in its interrupt 
manager, which intercepts the interrupts, saves registers, and calls the 
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driver’s interrupt service routine. The details of OS/2 interrupt 
management are discussed elsewhere. 

When the interrupt request line is asserted to the 80286, the chip 
completes execution of the current instruction and then jumps to an 
interrupt routine. Before jumping to that routine, the processor stack is 
switched to a system stack which is shared amongst all interrupts and 
the processor interrupt flag is disabled, disallowing any further inter¬ 
rupts. The interrupt routine is then executed and when it terminates with 
a processor Return From Interrupt (IRET) instruction, execution resumes 
at the interrupted instruction. It is the responsibility of the interrupt 
routine to save all registers it will use at entry and restore those registers 
befqre exiting. 

The detailed sequence of events when the processor interrupt line is 
asserted is somewhat more complex. The processor samples the interrupt 
flag in the Processor Status Word (PSW) when it completes each 
instruction, and if clear, executes the next instruction (ignoring the state 
of the interrupt request line). The interrupt flag of the PSW may be set 
with the processor Set Interrupt Flag (STI) instruction, and cleared with 
the processor Clear Interrupt Flag (CLI) instruction. 

If the interrupt- flag of the PSW is set, the processor samples the 
interrupt request line. If the interrupt request line is asserted, the 
processor switches to the interrupt stack and asserts the interrupt ac¬ 
knowledge line. The processor then expects to read the Interrupt Request 
Number (IRQ) from the data bus. Each IRQ is associated with a device 
driver interrupt routine. 

Additional interrupt support hardware is required to provide-the IRQ 
upon request from the processor. The standard hardware interrupt con¬ 
troller used on both the AT and PS/2 lines, is the 8259 Programmable 
Interrupt Controller (PIC). The 8259 PIC has eight inputs, each of which 
is driven by a different device controller. The PIC associates each device 
with a different IRQ from 0-7. If multiple PIC inputs are asserted by 
different controllers, the PIC prioritizes the inputs, and places the IRQ 
number associated with the highest priority device on the bus—in 
response to the processor’s assertion of the interrupt acknowledge line. 

Both the AT and PS/2 machines actually use two PICs cascaded 
together in a master/slave configuration (see Figure 1-2). The master PIC 
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generates IRQ 0-7 for its eight inputs, with IRQ 2 reserved to flag the 
master PIC that the slave PIC is requesting an interrupt. The slave PIC 
generates IRQ 8-OFh and thus, 15 distinct interrupt levels are available 
to device controllers on these machines (except level 2 which is reserved 
for master/slave PIC communication). 

Figure 1-2: Interrupt Hardware_ 
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The PICs on the AT are programmed to be edge-triggered; that is, 
sensitive to the transition in the device controller’s interrupt request line. 
When this transition takes place, the PIC remembers its occurrence and 
arbitrates among the various requests waiting to be serviced. Were a 
second transition to take place on the same line, the PIC would be unable 
to recall and arbitrate the second request. Thus, each input line of the 
PIC can represent only one device. The End of Interrupt (EOI) event must 
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be signalled to the PIC by the processor in order to clear the latched 
request. 

The PICs on the PS/2 are level-sensitive, such that the PIC arbitrates 
among all asserted input lines. In this case, several device controllers can 
share a single input line. When the interrupt request for the first control¬ 
ler is dismissed, the interrupt request line remains asserted if other 
devices are asserting the interrupt line. In this case, a single IRQ line 
may be shared among several device controllers, and among several 
interrupt routines. An EOI condition must be issued to the PIC to clear 
the request after the device interrupt request has been cleared. 

We can now examine in detail the sequence of events surrounding an 
interrupt request. Each device controller has an interrupt request line 
that is connected to one of the PIC inputs. When one or more controllers 
asserts an interrupt request, the PIC asserts the processor interrupt 
request line. 

The processor checks the interrupt flag of the PSW at the end of each 
instruction. If set, the processor then checks the processor interrupt 
request line. If the processor interrupt request line is asserted by the PIC, 
the processor switches to the interrupt stack and asserts the interrupt 
acknowledge line. When the PlC senses assertion of the interrupt ac¬ 
knowledge flag, it places the IRQ number of the highest priority device 
requesting interrupt on the bus. The processor uses this number to 
determine which interrupt routine to execute. Ih'OS/2, this routine will 
always be the interrupt manager, which in turn calls the driver interrupt 
service routine. 

The processor then saves the PSW on the stack, clears the interrupt 
flag, and performs a FAR CALL to the interrupt routine of the device 
driver. The interrupt routine saves any needed registers and performs all 
necessary data handling actions to the device controller. The interrupt 
routine clears both the PIC’s interrupt request and the device interrupt 
request (by issuing a command to the device controller). The interrupt 
routine then restores all registers and performs an IRET instruction, 
causing execution to resume at the interrupted instruction (the IRET 
instruction restores the old PSW, CS and IP, and the old stack). 
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1.1.3 Process Management Hardware 

The 80286 supports multitasking, providing segmentation, protection, 
relocation, and virtual memory functions. The device driver writer must 
consider these issues. 

An OS/2 thread is a context consisting of registers, a priority, and a 
stack (for device drivers, thg.jtack.is_ about 90Q_bytes long). Each OS/2 
thread operates in an address space owned by its process. A single stack 
of default length 2K bytes is used to service all interrupts. If the driver 
allows interrupts from a high priority device to be processed while a low 
priority device is being serviced (so as to reduce interrupt response time), 
the driver writer must allow for the heavier stack usage. Nested inter¬ 
rupts, or interrupts where a device may interrupt its own service routine, 
may also be desirable—but if naively written, they place an unpredictable 
demand on the shared stack. 

Physical memory on the 80286 is conventional 8-bit memory with 24-bit 
addressing. Amaximum of 16M bytes of physical memory may be installed 
on an 80286 system. However, the 80286 lacks the capability of directly 
addressing physical memory. 

80286 addressing is based on a segmentation scheme. Each address is 
composed of a selector that describes the segment, and an offset into the 
segment. The selector value is an index into a segment descriptor table 
containing the length of the segment and its starting (physical) address 
in memory. Each descriptor entry is 8 bytes long. The selector’s low order 
three bits are ignored when computing the descriptor table address and 
thus, the 16-bit selector value directly indexes an entry in the descriptor 
table. 

There are two address spaces on the 80286: the global address space 
and the local address space. When a task is operating under OS/2, it uses 
the local address space which is described by the Local Descriptor Table 
(LDT). One LDT is allocated to each process which operates under OS/2. 
The global address space is shared by the OS/2 kernel and device drivers. 
A device driver may therefore access any memory belonging to the kernel. 
The global address space is described by the Global Descriptor Table 
(GDT). 
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A third descriptor table, the dnterrupt-DescriptoFTable (IDT), is also 
provided. Thi§-tablepr<3vides theaddressofthe interrupt service routine 
to-be-associated with-eachinterrupt; This table may also be accessed by 
the device driver (although this access is not condoned by Microsoft). 

A thread that wishes to address memory must place a selector into a 
selector register labeled CS, DS, ES, or SS. The selector addresses a 
descriptor in the selected descriptor table (LDT or GDT). The segment 
that is described may now be accessed with the offset contained in an 
index register (SI, DI, BP, or BX) or an offset register (IP or SP). These 
registers are 16 bits in length and therefore, segments are limited to 64K 
in length. 

The address space of an OS/2 process is described in the LDT. All 
threads of that process share the same LDT and can freely exchange data. 
However, each process owns a separate LDT and cannot interfere with 
the address space of another process. Protection is further implemented 
with a feature called ring privilege. OS/2 user processes normally run 
at ring 3, the lowest level of protection. Ring 3 processes can only access 
ring 3 selectors, which OS/2 places in the LDT. User processes therefore, 
cannot access global segments and cannot interfere with system function¬ 
ing. 

OS/2 allows segments to be definedas "IOPL" segments with the linker. 
These segments run at ring 2. Ring^ processedalso may not access global- 
segments. Note that DLL libraries often run at ring 2 or ring 3. The OS/2 
kernel and device drivers run at ring 0. This gives them privilege to access 
both globed and local segments. 

Use of selector registers to address descriptors isolates the program 
from knowledge of, or dependence on, the physical address of the segment. 
OS/2 may relocate the physical address associated with a selector without 
impacting a user process. However, this may not be true for a device 
driver. The device driver must lock all segments that it will use against 
relocation. 

Each segment is associated with a 16-bit length, and may be up to 64K 
bytes in length. The number of available selectors in the GDT and the 
LDT is as many as 8K Multiplying these numbers gives a mayimnm 
address space of 512M bytes for the local address space, and another 512M 
for the global address space. Yet physical memory is limited to 16M! 


/ 


i 
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Segments need not be in physical memory to be addressed. This is a 
property of the 80286 called virtual addressing. Each address space is 
kept on a virtual device such as a disk, and only those parts of the address 
space in immediate use are cached in memory. If a thread attempts to 
access a segment which is not in memory, a segment not present fault 
takes place and OS/2 loads the required segment from virtual storage. 
The device driver cannot allow data to be swapped out to virtual storage, 
and must therefore lock its memory against swap. 

1.1.4 Real Mode 

A final and extremely important consideration for the driver writer is 
8086 compatibility. The 80286 chip provides 8086 compatibility operation, 
known as real mode. The 80286 operation mode in which protection is 
active is known as protect mode. rThe current mode of operation is 
^recorded in bit 0 of the machine status word (not the PSW). 

In real mode the exact same instruction set and registers are available 
to the driver writer. However, the interpretation of segment registers is 
quite different. Note that the name of these registers is even different— 
CS, DS, ES and SS are called selector registers in protect mode and 
segment registers in real mode. 

Segment registers contain the high-order 16-bits of a physical 20-bit 
address. An offset register is added to this value to compute a 20-bit 
physical address. Since these addresses are 20-bit, only 1M of address 
space is available. As the addresses are physical, no protection is provided. 

OS/2 supports a feature called the DOS 3.x Compatibility Box that 
simulates functional compatibility with the DOS operating system. The 
processor runs in real mode while simulating DOS. Since device driver 
commands may be issued and interrupts may be received while operating 
in the compatibility box, device drivers should be written to support both 
real and protect mode. Considerable effort was expended by Microsoft to 
allow the driver writer to construct these bi-modal drivers. 

In some cases, the OS/2 environment can be controlled and configured 
without the compatibility box. If driver writers can be guaranteed their 
drivers will never be run under a version of OS/2 that is configured to 
support the compatibility box, they may write their drivers without real 
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mode support. While this may not drastically simplify the actual driver, 
the design and debugging efforts will be lessened. Certain drivers may 
only run in real mode. These drivers need not support protect mode and 
may be DOS-compatible. 

1.2 OS/2 Overview 

The device driver is as much dependent upon OS/2 software architecture 
as it is upon the underlying 80286 hardware. The driver is sensitive to 
issues of OS/2 process and thread management, file management, 
memory management, semaphore coordination, timer management, 
character monitors, compatibility box support, and access to operating 
system variables. 

1.2.1 Process and Thread Management 

The thread is the OS/2 unit of execution. A thread operates in the context 
of the owning process and has its own registers, stack, and priority level. 

Threads can operate in ring 3, 2, or 0 context. Ring 0 operation is 
reserved for device driver and OS/2 kernel use. A thread’s address space 
is specified by the LDT of the owning process, and a ring 0 thread may 
also use the global address space as specified by the GDT. Ring 0 threads 
are given a stack of about 900 bytes for their own, private, use. 

Ring 2 and 3 threads are scheduled for execution each 31.25 mil¬ 
liseconds on the AT and PS/2 families. Each clock tick causes the 
scheduler to examine the queue of waiting threads for threads of greater 
priority. If a thread of higher priority is waiting for execution, the current 
thread is suspended, and the new thread is started. 

“RingD threads cannot be mterrupted by the scheduler. Once started, 
these threads have absolute control of the processor, yielding only to 
hardware interrupt requests. A ring 0 thread may suspend itself for later 
activation by an interrupt routine or some other thread. When restarted, 
the ring 0 thread once again owns the processor. 

Aprocess is a unit of OS/2 resource management. Aprocess owns a local 
address space, one or more threads, allocated memory, files, and 
semaphores. If it terminates, OS/2 recovers all objects owned by that 
process. Non-OS/2 resources may also be managed by a process exit list. 
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1.2.2 File Management 

Requests for I/O operation are made by the application when it issues 
various device-oriented API calls (DosOpen, DosRead, DosWrite, Dos¬ 
Close, and DosDevIOCtl). Simple requests (DosRead, DosWrite, and 
DosDevIOCtl) cause formatting of I/O request packets and are forwarded 
directly to the kernel. More complex requests (DosOpen and DosClose) 
are sent to the file manager, where they may cause a sequence of request 
packets to be formatted and sent to the kernel. The kernel dispatches a 
ring 0 thread to the device driver to service the request, and when the 
driver completes packet service, returns error status to the caller (applica¬ 
tion program or file manager). Note that the file manager runs in protect 
mode only, so an API call issued in the compatibility box which requires 
use of the file manager will cause context switch into protect mode. 

The file management system supports three I/O modes—block I/O, 
character I/O, and Generic I/O Control (IOCtl). Block I/O and character 
I/O are mutually exclusive models, but IOCtls may be used within either 
model. Generally, block I/O requests are routed through the file manager 
(except DosRead and DosWrite requests), and character and IOCtl re¬ 
quests are routed directly through the kernel (except DosOpen and 
DosClose requests). 

The block I/O model is used to drive block-oriented devices such as disk 
drives, tape drives and RAM drives. The drive name is limited to a single 
character ("A:" through "Z:"), limiting the total number of drives to 26. 
Device characteristics such as sector size and number of sectors on the 
device are made known to the file manager through the Bios Parameter 
Block (BPB). The device driver must be able to format and transmit the 
BPB to the file manager on request. 

The file manager supports only DOS-compatible data formats on block 
devices. The device must have equal-length sectors that are randomly 
addressable. Sectors are allocated in clusters whose availability is 
recorded in a reserved area called the File Allocation Table (FAT). The 
entire disk is divided into Boot (Reserved) Sectors, the FAT, the root 
directory, and the file data area. 

Any device that does not conform to the block I/O model must use the 
character I/O model. Character device drivers can perform special func- 
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tions such as keyboard and clock management. Generally, these drivers 
can read or write serial streams of data. 

Character devices support a monitor mechanism that allows intercep¬ 
tion of characters in the input or output stream by a chain of monitor 
threads. The monitor dispatcher processes each character and deter¬ 
mines if the character is to be translated or deleted from the stream. 
Characters written back to the monitor chain are in turn passed to the 
next monitor thread in the chain. When the last monitor thread in the 
chain has written data back to the chain, the data is transferred to the 
device driver to be written finally to the device. The device driver code 
that is called when the data has been made available is called the 
notification routine. 

The IOCtl model allows custom requests to be formatted and passed to 
the device driver. Many IOCtl functions are predefined for special han¬ 
dling of certain devices such as printer, mouse, physical device control, 
serial port, and character monitors. Drivers written to support these 
devices should support these IOCtls. 

1.2.3 Memory Management 

Memory is allocated to processes using several memory management 
schemes. Memory allocated in this way is described in the LDT and is 
relocatable and swappable. The device driver cannot allocate memory of 
this type and in most cases cannot use it. The driver can access memory 
described in the LDT of a process only while it is r unnin g in the ring 0 
context of that process. Even in protect context, the driver will block if 
the virtual memory is not present in RAM. In other situations, the driver 
must lock user memory against relocation and swap and obtain its (fixed) 
physical address. The driver may now map the physical address to a 
selector when needed. DMA transfer may be performed to or from this 
physical memory address. OS/2 provides the device driver with physical 
memory allocation/deallocation/mapping support. 

1.2.4 Semaphores 

Semaphores are of two general types: system semaphores and local 
semaphores. The device driver may create local semaphores by allocating 
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RAM to this purpose. The RAM required to create the semaphore may be 
described in global memory for device driver synchronization, or in a 
process LDT for coordination between threads and driver. System 
semaphores cannot be created by the device driver. 

Semaphores of both types may be used by the device driver. System 
semaphores must be converted to a form usable by the device driver and 
RAM semaphores must be made addressable before use. The driver can 
request a semaphore while executing in ring 0 context. If the semaphore 
is not clear, the thread will be blocked until the semaphore becomes 
available. 

The driver may clear a semaphore while in ring 0 or interrupt context. 
In either case, any threads waiting for the semaphore are unblocked and 
resume execution. This feature allows coordination between interrupt 
routine and ring 0 contexts, or even between interrupt context and a user 
thread. 


1.2.5 The Compatibility Box 

The compatibility box runs in real mode, simulating the functions of DOS. 
Effort is made to simulate all functionality of DOS, including device 
hardware interface, software interrupt interface, and BIOS interface. 

Device drivers that are known to run only under the compatibility box 
and that intercept interrupts only in real mode, may be used without 
mo difi cation. These drivers will be initialized in real mode (as opposed to 
bi-modal drivers that are initialized in protect mode). 

DOS programs communicate with the operating system by means of 
the software interrupt. OS/2 contains software to intercept all software 
interrupts expected by DOS and to translate their requests into OS/2- 
compatible calls. 

Support is provided for execution of ROM BIOS routines by bi-modal 
device drivers. Situations where a device must be shared between the 
BIOS and protect mode programs result in unique problems. This situa¬ 
tion mainly occurs in design of the video and disk routines provided by 
Microsoft, and will not be examined in depth in this book. 

These interrupts may be intercepted by the device driver. A technique 
is supported for real mode chaining of these interrupts. When a driver 
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requests a software interrupt, it is provided with the address of the 
previous software interrupt entry point. When the driver is called at 
software interrupt time, it is the driver’s responsibility to pass this 
interrupt onto the next interrupt service routine with a processor FAR 
JUMP instruction (JMP) to this address. 

The device driver is expected to idle all protect-mode requests that want 
to use the controller. When all such requests have been either serviced or 
idled, the driver can execute the ROM BIOS routine on behalf of the 
compatibility box. The device driver locks the compatibility into the 
foreground (to prevent suspension of the BIOS routine), and performs the 
BIOS routine. When the BIOS routine is completed, protect-mode re¬ 
quests for service of the device are resumed. 

The compatibility box receives two interrupts not normally processed 
by OS/2 on AT and PS/2 computers. The compatibility box receives an IRQ 
0 interrupt every 55 milliseconds and receives the IRQ 8 interrupt every 
.98 milliseconds. OS/2 does not receive the IRQ 0 interrupt, and receives 
the IRQ 8 interrupt only every 31.25 milliseconds. Even when the IRQ 8 
interrupt is being received by DOS, a clock tick is passed to OS/2 each 32 
DOS clock ticks for scheduling purposes. 

1.2.6 Interrupt Handling 

Device interrupts are processed by the OS/2 interrupt manager before 
calling the interrupt entry point. Registers are saved before calling the 
driver interrupt routine and need not be preserved by the interrupt 
routine. The interrupt routine returns with a processor FAR Return 
(RETF) instruction, not a Return From Interrupt instruction (IRET). 

Shared interrupt levels are processed by the OS/2 interrupt manager. 
Each interrupt service routine is called in turn until one of them indicates 
(by clearing the Carry flag of the PSW) that it has serviced the interrupt. 
The OS/2 interrupt manager will then discharge the interrupt with an 
IRET instruction. 

1.2.7 Timer Handling 

OS/2 receives the IRQ 8 interrupt every 31.25 milliseconds on the AT and 
PS/2. This corresponds to a frequency of 32 clock ticks per second. The 
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primary purpose of this interrupt is to schedule threads running under 
OS/2 and allow for timed suspensions. 

The device driver may use this interrupt for its own purposes. OS/2 
provides a timer entry point for device drivers, which is called every 
clock tick. The device driver may specify that entry to this routine is to 
be made after a specified number of ticks (rather than just one). This timer 
entry point is called in protect mode interrupt context with interrupts 
enabled, without saving of registers. The timer routine is required to save 
all registers and restore them before returning. Return, however, is made 
with the processor FAR Return instruction (RETF), not the processor 
Return From Interrupt instruction (IRET). 

1.2.8 DOS Variables 

Certain standard variables are made accessible to the driver. These 
variables are updated by OS/2 to reflect serial port ownership, process 
status, and other information. 

The information that is accessible at both ring 0 and interrupt time 
includes the system INFO segment, the COM port words, the reboot 
vector address, and the yield flags. Ring 0 threads have additional access 
to the local INFO segment. 

The global INFO segment contains system-specific information. This 
information includes time of day, clock tick interval in milliseconds, OS/2 
version number, and a protect-only indicator flag (which tells the driver 
whether the compatibility box is supported). The local INFO segment 
contains process-specific data including screen group, process id, and 
thread id. The COM port words are set to 0 to indicate ownership of each 
serial port COM1 and COM2. 

If the driver executes the processor FAR Jump instruction (JMP) to the 
reboot address, the system is rebooted. 

The yield flags may be used in ring 0. Ring 0 routines cannot be 
interrupted by other threads. While a ring 0 routine performs extensive 
processing, no other thread will be run. If a higher-priority thread is 
scheduled but prohibited from running, these flags will be set and can be 
queried by the running thread. The running thread may then elect to yield 
execution to the higher priority thread. 
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1.3 Device Driver Overview 

A device driver is composed of a collection of code and data segments (as 
shown in Figure 1-3) contained in a conventional library load module 
produced by the linker with the LIBRARY directive of the .DEF file (a 
.DLL file). These segments are loaded into memory at initialize time and 
the driver is called to perform initialization actions. The routine in the 
driver that is called in process context at initialize time is called the 
strategy routine. Initialization is performed in the context of the in¬ 
itialization protect mode process at ring 3, and therefore many API calls 
may be used. DOS-only devices are initialized in real mode. 


Figure 1-3: Device Overview 
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Application programs issue API calls which are routed to the device driver strategy routine 
through the file manager and the kernel (some API calls bypass the file manager). The 
driver strategy routine starts device I/O, and blocks. Interrupts are received by the 0/S2 
interrupt manager and are passed to the driver interrupt service routine. The interrupt 
service routine issues the Run command to the unblock strategy routine. 
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1.3.1 Device Driver Entry Points 

When the device driver is loaded, the address of the strategy routine is 
specified in the main data segment. This address is called by the initialize 
thread and later by the kernel. 

The strategy routine is called by the kernel in the performance of I/O 
requests. The strategy routine is called in the context of the calling thread, 
and therefore, may be invoked in either real or protect mode. If called in 
protect mode, the strategy routine executes in ring 0. If called by the file 
manager, the strategy routine will be executed in protect mode. 

Whether called by the initialization process, or in response to a thread’s 
I/O request, the strategy routine receives an I/O request packet that 
represents the action to be performed by the driver. The strategy routine 
interprets the I/O request packet contents and satisfies the request (or 
returns an error code). Typically, the strategy routine starts the device 
operation and blocks. 

The device driver supports several entry points in addition to the 
strategy routine—interrupt entry point(s), timer entry point(s), notifica¬ 
tion entry point(s), and an inter-device communication point. These entry 
points must be specified by the strategy routine when needed. 

The interrupt entry point is called by OS/2 (see Figure 1-4) in response 
to a hardware interrupt request. The interrupt service routine performs 
necessary device management and mapping of user buffers. Since the 
interrupt routine may be called in either real or protect mode, addresses 
that are to be shared between the two contexts must be mapped by each. 
Addresses to be used by the driver normally are stored as physical 
addresses. Registers are preserved by the interrupt manager and need 
not be saved by the interrupt service routine. 

The device driver can specify a timer entry point and the number of 
clock ticks between calls to that point. The cloek tick interval-is fixed at 
'3Tr25 milliseconds=on=the-AT and_ES/2./rhe timer routine will be called 
in protect mode in interrupt context, with interrupts enabled. Registers 
are not preserved with this call, and must be saved and restored by the 
timer routine. 
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Figure 1-4: Device Driver Entry Points 
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Character device drivers support monitor chains. The flow of data 
through the device driver may he written to a monitor chain. This data 
will be processed through all monitors in the chain, and the modified data 
stream is written to a final buffer. The notification entry point is then 
called to finish processing the data and to satisfy the original I/O request. 
The notification routine may be called in the context of the monitor control 
thread (ring 0) or in the context of the routine that wrote the data, if the 
monitor chain was empty. This context may be interrupt context in real 
or protect mode. 

The inter-device communication entry point is used to communicate 
between device drivers. There is no standard communications packet, so 
the communicating drivers must agree on a protocol. The calling driver 
is also required to set up certain communication registers before calling 
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the target routine. The contents of these registers are sensitive to the 
real/protect mode of operation. 

1.3.2 Device Helper Routines 

The device driver cannot make API calls (except in initialization mode). 
OS/2 supports a device helper entry point to provide device driver ser¬ 
vices. The device driver entry point is provided to the driver at driver 
initialization time, in the initialize I/O packet. The address of this routine 
must be stored by the device driver for later use. 

Device helper routines provide the device driver with process manage¬ 
ment, memory management, interrupt management, timer management, 
semaphore management, request queue and character queue manage¬ 
ment, monitor management, and system service functions. 

Process management functions include blocking and unblocking of 
the strategy routine, changing mode of operation from real to protect, and 
yielding the strategy routine to high priority threads. 

Memory management functions include allocation of physical 
memory, locking of virtual addresses, and translation of addresses from 
virtual to physical. 

Interrupt management functions include allocation of hardware in¬ 
terrupt vectors and PIC management. 

Timer management includes establishing a timer entry point, and 
establishing the count of clock ticks between calls to the timer entry point. 

Semaphore management includes converting a system semaphore 
handle for driver use, requesting a semaphore, and clearing the 
semaphore. Local semaphores may be allocated in the address space of 
the device driver, but system semaphores may not be allocated by the 
driver. 

Queue management includes I/O request packet queue management 
and character queue management. These routines are provided for the 
convenience of the driver writer. The I/O request packet queue is used to 
store a list of pending requests to be processed by the driver. The character 
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queue is used to store a list of characters awaiting transmittal to the 
driver, or a list of received characters waiting to be read by an application 
program. 

Monitor management includes creation of a monitor chain, registering 
a monitor thread to the chain and writing data to the chain. 

System service functions include obtaining DOS variables and special- 
purpose functions. These special functions include support of BIOS calls 
from within a bi-modal driver, and special functions needed by the 
DRIVER.SYS driver, the keyboard driver, and the clock driver. 

1.3.3 Bi-modal Support 

Most device drivers written for OS/2 will be required to support the 
compatibility box. This means these drivers must be able to function 
regardless of whether they are called in real or protect mode, and whether 
they receive interrupts in real or protect mode. 

OS/2 provides bi-modal support for many driver structures. This sup¬ 
port is provided by means of tiled=selectors= and special interrupt 
handling support. 

A tiled selector is a selector that points to an area of low memory whose 
physical address is chosen in a special way. If used in protect mode, the 
selector points to a descriptor whose contents address that physical 
address. If used in real mode, the address calculation results in the same 
physical address. Asingle tiled selector may bemused to represent the same 
physical address whether used in real mode or protect mode. 

Tiled selectors are had at a premium, and are used by OS/2 only when 
absolutely necessary. I/O request packets are accessed by tiled pointers, 
and-fheaddress ofthedevice/helper entrypointisalso tiled. 

The device driver code segment and data segment are not tiled! When 
the OS/2 interrupt manager receives a hardware interrupt, it determines 
which driver is to be called. The interrupt manager then determines the 
processor state, real or protect. Based on the current processor state, the 
interrupt manager loads the DS register to point to the driver main data 
segment and sets the CS register to point to the main driver code segment. 

In some cases, the device helper routines will cause a processor mode 
switch—from real to protect mode, or from protect to real mode. When 
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this translation takes place, the DS and ES are examined for the current 
data segment value. If present, the register is converted to the new mode’s 
value. Needless to say, any stored pointers that contain the data selector 
value, will be invalid after the mode change. Stored far pointers will not 
be translated by this process and their contents will not be valid in the 
new context. ' 

If a ring 0 thread suspends execution, it is guaranteed to resume in the 
same process context, with interrupts enabled. 



CHAPTER 2 


DEVICE DRIVER STRUCTURE 


2.1 Segment Structure 

The device driver is contained in a standard load library module (a .DLL 
file) that is produced by the linkage editor LINK with LIBRARY option 
specified in the .DEF file. The first segment of the file is considered by 
the initializ ation loader to be the main data segment of the device driver. 
This segment will be loaded into memory accessible by both real and 
protect contexts (only 1M of physical memory is addressable in real mode), 
and DS (the data segment register) will point to this segment at strategy, 
interrupt, timer, and notification entiy. 

The second segment of the load module is considered by the initializa¬ 
tion loader to be the main code segment of the device driver. This segment 
will also be loaded into low memory, and CS (the code segment register) 
will point to this segment at driver entry. 

Stack-spaceds-alloeated-to the driver-from low memory. The main code, 
main data, and stack segments are not given tiled (bi-modal) addresses, 
and so the CS, SS, and DS will change if the processor is caused to change 
state from real to protect mode, or from protect to real mode. Long pointers 
into the driver segments normally should not be stored for later use, as 
the context of the driver at each entry point cannot be known in advance. 
See Figure 2-1 for the layout of device driver memory. 


23 
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Figure 2-1: Device Driver Memory Layout 



Additional segments, if present, are loaded into high memory (above 
1M). These segments are addressable only in protect mode. 

Since pointers to these segments are fixed, they may be stored as 
desired. References to data in these segments will be resolved by the 
initialization loader. 

Additional segments are discarded by default after initialize time. This 
is convenient for the removal of unnecessary initialization code and data 
after initialization is complete. To retain any additional segments, mark 
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them as IOPL segments at link time (use the IOPL option in the .DEF 
file). They will then be retained permanently for driver use. These 
segments must be locked against swap by the device driver to be used at 
interrupt time. 

2.1.1 The Main Data Segment 

The main data segment must contain device header information at the 
beginning of its segment. The information contained in the device header 
is used to perform initialization functions and to configure the file 
manager interface to the device driver. Character device drivers may 
support several devices in a single driver file; and if this driver is expected 
to handle multiple devices, a device header should be present in the main 
data segment for each device. These driver headers are linked together 
in a simple linked list. 

At initializ e time, the initialization loader calls the entry point in the 
main code segment specified in the first driver header. The driver strategy 
routine performs needed initialization and modifies additional headers 
as required. When the strategy routine returns to the initialization loader, 
the loader examines the link word of the current header and, if the link 
word is not -1 (OFFFFFFFFh), uses it as a FAR pointer to the next header. 
The strategy routine is called again to initialize the second device. 

The device driver is not given the address of the header being initialized 
by the ini tialization loader, so it is the responsibility of the strategy 
routine to keep a count of headers that have been initialized and to chase 
the list of device headers as required. 

Following the link doubleword in the device header is the device 
attribute word (DAW). This word contains various descriptive informa¬ 
tion used by the initialization loader and the file management system. 
Initializ ation information contained in the attribute word include 5 bits 
labeled IDC, CLK, NUL, SCR, and KBD; and a 3-bit field labeled LEVEL. 

The IDC bit is a flag which, if 1, indicates that this driver contains an 
inter-device communication entry point. If present, the address of this 
entry point will be communicated to a device driver which requests it. 
Only character devices support the IDC entry point. 
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The CLK, NUL, SCR, and KBD flags are special-device flags. Each flag, 
if 1, indicates that this device driver is to replace the system default driver 
for clock device, null device, standard output pseudo-device, or keyboard 
device, respectively. Each of these drivers is required to support special 
interface to OS/2. 

LEVEL is 000 for compatibility box drivers and 001 for OS/2 drivers. 
Compatibility box drivers are initialized in real mode, while OS/2 drivers 
are initialized in protect mode. A compatibility box driver should never 
be called in protect mode, and should not accept hardware interrupts 
(which might be generated in protect mode). 

File management information is contained in the 5 bits labeled CHR, 
IBM, SHR, OPN and GIO. The CHR flag is 1 for character device driver 
and 0 for block device drivers. The interpretation of the other bits is 
dependent upon this bit. Character device drivers require the IBM bit to 
be 0. 

The SHR bit in a character device driver indicates whether file manage¬ 
ment sharing rules should apply to this device. If 1, file system sharing 
rules will apply to this device. If 0, any ownership contention must be 
resolved by the device driver. Many character devices will resolve conten¬ 
tion within the device driver. 

The OPN bit for character device drivers, if 1, indicates that the driver 
requires an OPEN and CLOSE call from the file manager. These calls will 
originate with the user process, and may be used for arbitration of 
ownership if SHR is 0. If the character device supports generic I/O control 
calls (IOCtl), set the GIO bit to 1. 

Block device drivers are indicated by a 0 in the CHR bit. These drivers 
support file management calls such as OPEN/CLOSE and shared device 
access checking, and provide file system directory support. 

The IBM bit is set to 0 for block devices that support DOS 1.0 and 1.10 
file formats, and to 1 for block devices that support DOS 2.0 and above 
file formats. The SHR bit is 0 for block device drivers. 

The OPN bit is a removable media indicator for block device drivers. If 
1, removable media support is built into the driver. If 0, this support is 
not provided, and the file system is to assume fixed media. If the block 
device supports generic I/O control calls (IOCtls), set the GIO bit to 1. See 
Table 2-1 for a listing of all device attribute fields. 
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Table 2-1: Device Attribute Word 


FIELD 

BIT 

INTERPRETATION 

15 

CHR 

1 if this driver is a character device driver, 0 
if this is a block driver. 

14 

IDC 

1 if this character driver supports inter¬ 
device driver communication, 0 if not. 0 for 
block drivers. 

13 

IBM 

0 for character device drivers, 1 if block 
driver supports a 2.0 file format. 

12 

SHR 

0 for block device drivers, 1 if file system shar¬ 
ing rules apply to this character device driver. 

11 

OPN 

For character device drivers: 1 if 
OPEN/CLOSE is required. For block device 
drivers: 1 if removable media support is 
provided. 

10 

RESERVED 

0 

9-7 

LEVEL 

000 for real mode driver, 001 for OS/2 driver. 

6 

GIO 

1 if IOCtl support is provided. 

5,4 

RESERVED 

00 

3 

CLK 

1 if this driver replaces system clock driver. 

2 

NUL 

1 if this driver replaces system null driver. 

1 

SCR 

1 if this driver replaces system standard out¬ 
put driver. 

0 

KBD 

1 if this driver replaces system keyboard 
driver. 


Following the link doubleword and the attribute word in the device 
header come the offsets into the main code segment of the strategy entry 
point and the inter-device driver communication entry point. The strategy 
routine is called at initialize time, and by the kernel in response to user 
I/O requests. 
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The inter-device driver communication entry point is provided to other 
drivers upon request. There is no additional system support for this 
feature. Character device driver headers then contain the eight-charac¬ 
ter, blank-terminated, device name. This is the name by which the device 
will be known to the system, and to which the user will direct I/O requests. 
Block character devices do not use this name. The final 8 bytes of the 
device header are reserved. See Table 2-2 for a summary. 


Table 2-2: Device' Header 

OFFSET 

SIZE 

DESCRIPTION 

0 

4 

Far pointer to next device header, allowing multi¬ 
ple devices to be supported in one driver file. 
OFFFFFFFFh if last header in chain. 

4 

2 

1 

Device attribute word. 

6 

2 

Offset within code segment of strategy routine. 

8 

2 

Offset within code segment of IDC routine (charac¬ 
ter devices). 

>QAh 

8 

Eight-character, blank-filled name of character 
device driver. For block drivers the first byte is 
set by OS/2 to number of logical units supported. 

12h 

8 

Reserved. 


2.2 Strategy (I/O) Request Packets 

At entry to the strategy routine, a pointer to the request packet is 
contained in register ES:BX- (the address of the main data segment is 
contained in DS). This pointer is tiled (bi-modal), and may be stored for 
future reference in either real or protect mode. 

The request packet is composed of a 13-byte header followed by a 
variable-length, command-specific data section. The header contains a 
status field that is set by the driver to indicate completion of the request, 
and error code. The command-specific data contains input data to be used 
by the driver, and returns data to the requesting thread. Buffer addresses 
in the READ, WRITE, and BUILD BPB request packets are provided in 
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the command-specific area in locked, physical form. Buffer addresses in 
the IOCtl request packet are provided in movable, virtual form. 

2.2.1 Request Packet Header 

The 13-byte request packet header is composed of a 1-byte length field, a 
1-byte unit code, a 1-byte command code, a 2-byte status code, 4 reserved 
bytes, and a 4-byte linkage field. 

The length byte contains the total packet length, i.e., 13 plus the length 
of the command-specific data section. 

The block device unit number contains the unit number for which this 
request is intended. A block device driver may support multiple logical 
units, and so this mechanism provides the means of communicating the 
relative unit number to the driver. This field is used only for block device 
drivers. 

The command code communicates to the driver writer the operation 
which the driver is to perform. These operations include initialize device 
driver, d eins tall device driver, read/write data, generic I/O control, char¬ 
acter driver-specific functions, and block driver-specific functions. 

The status word is set by the driver to indicate status of the request. 
Four general states may be reported—device busy, request incomplete, 
request complete with error, and request complete with success. 

The queue linkage word may be used by the driver writer to form 
queues of request blocks waiting process. Table 2-3 illustrates the request 
packet header format. 


Table 2-3: Request Packet Header Format 

OFFSET 

LENGTH 

DESCRIPTION 

0 

1 

Length of request block, including header. 

1 

1 

Unit code, for block devices only. 

2 

1 

Command code. 

3 

2 

Status field, used to report completion status. 

5 

4 

Reserved. 

9 

4 

Queue linkage. 
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2.2.2 Functions Requested by Strategy Packet 

The command codes fall into the following categories—installation, nor¬ 
mal I/O, character device-specific I/O, block device-specific I/O, and 
generic I/O control. 

Two request packets are used in the installation process. These are 
INIT and -DEINSTALL. The INIT packet is passed to the strategy routine 
at initialize time, once to a block device driver and once for each device 
header for a character driver. The strategy routine executes in application 
context (ring 3) of the installation process, and thus some API calls may 
be issued by the driver. The DEINSTALL packet is issued when a second 
driver header for a character device has a name conflict with one already 
installed. In this case, a DEINSTALL packet is sent to the first driver. 
The first driver may elect not to deinstall, in which case the second driver 
will not be installed. 

"Normal" I/O requests include Device OPEN/CLOSE, READ, and 
WRITE. The Device OPEN and Device CLOSE requests may be used by 
the driver to initialize the device or to arbitrate ownership of character 
devices. The READ packet starts a device read and waits for completion. 
The characters read from the device are placed in the buffer whose locked, 
physical address is included in this packet. The WRITE packet writes 
data from the buffer whose locked, physical address is included in this 
packet. 


2.2.2.1 Character Device-Specific Requests Character device request 
packets include INPUT STATUS, OUTPUT STATUS, INPUT FLUSH, 
OUTPUT FLUSH, NONDESTRUCTIVE READ NO WAIT, and Monitor 
OPEN/CLOSE. The IOCtl functions, Query Monitor Support and 
Register Monitor, are supported by the character device. 

In response to the INPUT STATUS request, the driver simply sets the 
status word in the request packet header. The device will be marked 
"BUSY" if the driver has no characters waiting in the input buffer, and a 
READ request could therefore not expect immediate service. OUTPUT 
STATUS also marks the status word of the request packet header. The 
status word is set "BUSY" if the driver has an outstanding WRITE 
request, so that a WRITE request would expect to wait for service. 
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The INPUT FLUSH packet cancels all pending READ requests and 
flushes all input buffers, including monitor chains. The READ request 
packets are returned with a "Character I/O call interrupted" error (error 
llh). The OUTPUT FLUSH command cancels all pending WRITE re¬ 
quests and flushes the output queues, including monitor chains. The 
WRITE request packets are returned with a "Character I/O call inter¬ 
rupted" error (error llh). 

The NONDESTRUCTIVE READ NO WAIT request marks the status 
word of the request packet header "BUSY" if no characters are waiting 
for input. If the device input queue is not empty, the BUSY bit is cleared 
and the first waiting character is returned. This character will be the first 
character returned by the next READ request packet. 

The Monitor OPEN packet connects a process with a character device, 
and will often create a chain of character monitors that intercept data 
flowing to or from the device driver. One chain is typically created for each 
individual input or output data stream for each process accessing the 
driver. Only one Monitor OPEN packet is issued to the driver per process. 

The IOCtl call Register Monitor is used to register a monitor thread to 
one of the monitor chains of the device driver. Aprocess may register many 
monitors to the driver. 

Upon receipt of the Monitor CLOSE packet, the device driver is ex¬ 
pected to dereg is ter all monitor threads created by the process issuing the 
close, and destroy any monitor chains created for this process. 

The IOCtl call Query Monitor Support is issued to determine if 
monitors are supported by the device driver. 

2.2.2.2 Block Device-Specific Requests Block-specific request packets 
include write verify support, logical unit support, removable media sup¬ 
port, and physical device support. 

The WRITE VE RIF Y packet writes data from the buffer whose locked, 
physical address is included in the packet. The driver must then verify 
that the request was successfully completed, perhaps by attempting to 
read back the same data. 

Logical uni t support is provided for the file manager’s use. The file 
manager will request the device characteristics with the BUILD BPB 
request. The driver then formats and returns a BIOS Parameter Block, 


\ 
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a standard structure which returns the parameters that the file system 
will use for organizing the media. 

Additional logical unit support is provided in the form of Category 8 
IOCtl calls. IOCtl calls are issued by an application program, and these 
calls would normally be issued by a FORMAT program in the construction 
of a file system on a logical unit. Category 8 IOCtl calls are discussed 
further in Chapter 4. 

Removable device support is also provided for file manager use. The 
request packets providing this support include REMOVABLE MEDIA, 
RESET MEDIA, and MEDIA CHECK. REMOVABLE MEDIA queries the 
device to determine if the media is removable. The device driver sets the 
BUSY bit if the media is fixed, and clears the BUSY bit if the media is 
removable. 

RESET MEDIA orders the device driver to reset the media, performing 
any driver-dependent media checks (such as reading the BPB and the 
volume label). MEDIA CHECK requires the driver to set a return code 
indicating the media has been changed, unchanged, or the driver is 
unsure whether the media has been changed. The media state will be 
ordered reset by the file manager RESET MEDIA packet. Once the media 
state is uncertain or changed, all subsequent strategy packets should be 
returned with an "Uncertain Media" error (error lOh). 

Physical device support is provided by means of Category 9 IOCtl calls, 
typically issued by low-level FORMAT programs or disk partitioning 
program, FDISK Several logical units (file systems) can be supported on 
a single physical medium by means of a technique termed partitioning. 
The driver must interpret partition information and return to the file 
manager the number of logical units it supports. The file manager 
performs I/O only to logical units. 

IOCtl request packets provide device-dependent functions, device-in¬ 
dependent functions, and user-defined functions. Each IOCtl function is 
defined with a Category byte and a Function byte. The Category byte is 
used to select a class of functions, and the Function byte selects the 
specific function within that class. IOCtl calls are made by application 
programs directly through the kernel to the device driver, and do not flow 
through the file manager. System-defined IOCtl calls are normally 
reserved for system software use. 
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System-defined driver dependent functions are provided for serial 
device control, screen/pointer draw control, keyboard control, printer 
control, and mouse control. Each of these devices has its own Category 
code. Table 2-4 fists the different devices and their category codes. 


Table 2-4: System-defined IOCtl Category Codes 

CATEGORY 

DEVICE 

1 

Serial Driver 

2 

Reserved 

3 

Screen/Pointer Draw 

4 

Keyboard Driver 

5 

Printer Driver 

6 

Light Pen Driver 

7 

Mouse Driver 

8 

Logical Unit Control 

9 

Physical Drive Control 

OAh 

Character Monitor Control 

OBh 

Character Device Control 


System-defined driver independent functions are provided for logical 
unit control, physical drive control, character monitor support, and to 
flush input or output queues. 

A function is provided to query monitor support. If the device driver 
supports character monitors, the status word should be set to no error. If 
monitor support is not provided, the "Monitors not supported" error (error 
12h) should be returned. 

A second function is provided to register a monitor on the monitor chain. 
The device driver is solely responsible for maintaining the monitor chain, 
so requests to add monitors are translated from the application’s DosMon- 
Reg API call into the Register Monitor IOCtl, which is forwarded to the 
device driver. 

Flush Input Buffer and Flush Output Buffer IOCtls are provided to 
force flus hin g of input and output buffers, respectively. The device driver 
is expected to flush any monitor chains, and return all pending READ or 
WRITE requests with the error "Character I/O call interrupted" (error 
llh). These functions are compatible with the strategy packets INPUT 
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FLUSH and OUTPUT FLUSH. These functions are provided for use 
outside the file management system, and for historical compatibility with 
DOS. 


2.3 Device Helper Services 

The address of the device helper routine is contained in the INIT request 
packet. This is a tiled address so the driver may save it for later use 
without regard for real/protect mode context. 

The driver performs a FAR CALL to the device helper service entry 
point with the service code contained in register DL. Arguments to the 
helper service are contained in registers. The register arguments follow 
no general pattern. Device helper services may be broken down into the 
following general categories: process management, memory manage¬ 
ment, interrupt management, semaphore management, timer manage¬ 
ment, device driver communication, character monitor management, 
request queue and character queue management, and system services. 

2.3.1 Process Management 

Process management functions are used to block and unblock the strategy 
routine, to yield the strategy routine to higher priority threads, and to 
convert real mode to protect mode. 

The strategy routine is entered in real mode or ring 0 of the calling 
thread context (except the initialization routine, which is entered in ring 
3 of the initialization thread context). This thread will usually place the 
request packet contained in ES:BX on a queue, and possibly start device 
I/O. The strategy routine would then block, waiting for interrupt service. 
When the interrupt service routine determines the I/O request has been 
satisfied, it unblocks the strategy thread, which then sets or clears the 
error code, marks the packet as done, and returns. The device helper 
routines that perform these functions are called Block and Run. 

Block may be called from strategy context, but not from interrupt 
context (interrupt context must always run to completion without suspen¬ 
sion). If interrupts are disabled when the thread calls the Block command, 
they will be enabled when the thread resumes. Block takes a 32-bit event 
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identifier which should uniquely specify this thread. The address of the 
strategy packet is normally used as the event identifier. 

Run maybe called from either strategy or interrupt context, and takes 
a 32-bit event identifier as argument. All threads blocked on this identifier 
will be rescheduled. 

A second OS/2 coordination facility is provided for use of strategy 
routines. The strategy routine can queue the request packet and start 
device I/O, and then mark the status word of the request packet incom¬ 
plete (DONE bit = 0). The strategy routine then returns with the address 
of the strategy packet in ES:BX, and the OS/2 kernel blocks the thread. 
When the interrupt routine determines I/O completion, it sets or clears 
the error code, marks the packet done, and calls the DevDone device 
helper routine. The interrupt service routine may then start servicing the 
next waiting packet, or return. 

Once a strategy routine starts executing, no other threads will be run 
by the scheduler. If the strategy routine is expecting to perform lengthy 
processing, it may be able to interrupt that processing to allow higher 
priority threads a time-slice. If so, the thread periodically (the recom¬ 
mended period is 3 milliseconds) checks the Yield flag which is set by the 
scheduler if a high priority thread is waiting to run. If this flag is set, the 
thread executes the Yield device helper routine. 

The thread may elect to yield only to threads of time-critical class, and 
not to higher priority threads of the same class. If this is the case, the 
thread periodically (the recommended interval is 3 milliseconds) checks 
the TCYield flag, which is set by the scheduler only if a time-critical 
thread is ready to run. If this flag is set, the thread executes the TCYield 
device helper routine to yield to the waiting thread. The Yield flag and 
TCYield flag are accessed with the GetDOSVar driver helper routine. 

Real to protect mode change is effected with RealToProt and ter¬ 
minated with ProtToReal. The current status of the thread (real/protect) 
may be checked by examining bit 0 of the processor status word. 

RealToProt is used to change the thread state from real mode to 
protect mode. This may be necessary in order to address high memory 
code segments, or for programming simplicity. The processor mode must 
be restored before blocking the thread or returning from the strategy 
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routine. ProtToReal is used to return the thread state from protect mode 
to real mode. 

2.3.2 Memory Management 

Memory management functions include physical memory allocation, al¬ 
location of selectors, locking and mapping virtual memory, and vir¬ 
tual/physical address conversion. 

Physical memory is allocated with the AllocPhys helper function, and 
deallocated with the FreePhys function. Physical memory may be allo¬ 
cated in any size up to all available contiguous memoiy, and may be drawn 
from high (above 1M) or low (below 1M) memory. This memory cannot be 
addressed by the 80286 until it is mapped to a selector. Selectors may be 
allocated in the global descriptor table, and in the local descriptor table. 

Global selectors are allocated with AllocGDTSelector at initialize 
time only. These selectors must be mapped to physical memoiy before use. 
Once mapped, these selectors may be used in any protect context, but 
should not be passed by an application to an API call. Local selectors are 
allocated (and mapped) with PhysToUVirt. This call maps physical 
memory to a local selector that may be used only in the context of the 
process which owns the thread in which the call is made. These selectors 
should be deallocated when no longer needed (with PhysToUVirt). 

Virtual memory may be mapped with PhysToGDTSelector, 
PhysToUVirt, and PhysToVirt. PhysToGDTSelector maps physical 
memory to a global selector. The maximum amount of memory that can 
be mapped to a selector is 64K bytes, larger amounts of physical memory 
must be mapped in segments. This mapping may be made in protect mode 
in strategy or interrupt context, and is usable later in either context 
(protect mode only). PhysToUVirt maps physical memory to a local 
selector, or releases a local selector mapped earlier with PhysToUVirt. 
This mapping may be made only in strategy context (real/protect), and 
the returned selector is valid for use only in the context of the same 
process that owns the allocating thread. PhysToVirt is used for the 
short-term mapping of one or two selectors. OS/2 allocates two global 
selectors for each interrupt level and an extra two for protect mode 
strategy context. Thus the PhysToVirt mapping must be terminated 
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before blocking the strategy thread or reenabling the PIC in the interrupt 
service routine. If called from real mode, PhysToVirt may use the undocu¬ 
mented 80286 LOADALL diagnostic instruction, or switch into protect 
mode on the 80386—thereby invalidating previous address translations. 
The PhysToVirt translation is released with UnPhysToVirt. 

Virtual memory can be accessed at interrupt time only if it is present 
in memory, and can be mapped to a selector. Virtual memory is locked and 
converted to a physical address before strategy entry with the READ and 
WRITE request packets; this physical address may be temporarily 
mapped by the interrupt routine for immediate use. Addresses passed by 
the IOCtl request packet are virtual addresses and must be locked and 
converted to a physical memory address for use by the interrupt routine. 

Virtual memory is locked against relocation or swap by the Lock helper 
routine, and should be unlocked with the Unlock helper routine when 
no longer needed. Virtual memory, once locked, is converted to a physical 
address with VirtToPhys. This physical address may now be used at 
interrupt time to map the segment for access in the context of the 
interrupt routine. 

The strategy routine may determine if a virtual address is valid in the 
underlying thread context with VerifyAccess. Invalid addresses will 
cause termination of the underlying process. 

2.3.3 Interrupt Management 

Interrupt management includes hardware interrupt interception, 
programmable interrupt controller (PIC) management, and software 
interrupt interception. Interrupts are disabled or enabled with the proces¬ 
sor instructions CLI and STI. 

Hardware interrupts are intercepted with the SetIRQ helper request. 
IRQ levels O-OFh (except IRQ 2) represent device interrupts on the AT 
and PS/2 machines and can be intercepted by interrupt service routines. 
UnSetIRQ is used to release an IRQ level that is no longer needed. 

When the interrupt routine has cleared the device controller, and is 
capable of accepting a nested interrupt, the interrupt service routine 
clears the PIC for its IRQ level. The EOI helper service is used to clear 
the PIC, and to enable subsequent interrupts at the same level. 
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2.3.4 Semaphore Management 

Semaphores are used by the driver to coordinate between application and 
strategy threads, or between interrupt and strategy threads. Standard 
process-control synchronization primitives are more efficient than 
semaphores and should be used whenever possible. 

Semaphore management falls into two categories—system and non¬ 
system semaphores. System semaphores cannot be allocated by the device 
driver, but they may be used by the driver if created by a user process. 
The system semaphore handle must be converted to a driver handle before 
use with SemHandle. SemHandle also increments the semaphore usage 
count, and so SemHandle must be called again to release the semaphore 
when it is no longer needed. 

Non-system semaphores are created in RAM by the driver or the user 
process. The area of RAM must be locked and converted to an address 
usable by the device driver if it is to be used at interrupt time. If 
SemHandle is called with the address of a non-system semaphore, it will 
return the address unchanged and will verify that the address is valid in 
the thread’s address space. The only non-system semaphore supported in 
the device driver is the RAM semaphore (a 4-byte memory area). Sem¬ 
Handle may be called in strategy or interrupt context. 

SemRequest is used to gain access to the semaphore. SemRequest 
takes the handle returned by SemHandle as its argument and blocks the 
calling thread until the semaphore is cleared. Since this request may 
block, interrupts may be enabled on return, and SemRequest may not be 
used from interrupt context. 

SemClear unblocks all threads waiting on a semaphore. SemClear 
may be called in strategy or interrupt context. The highest priority 
waiting thread will obtain the semaphore. 

The signalling function and fast, safe non-system semaphores are not 
supported in the device driver. 

2.3.5 Timer Management 

The system time generates a clock tick every 31.25 milliseconds on the 
AT and PS/2. A timer interrupt entry point may be specified to be called 
each tick, or every fixed number of ticks. This timer may be used for 
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time-out processing or device polling. All registers must be preserved and 
restored by the timer routine. 

SetTimer helper service is used in the strategy routine to allocate a 
timer entry point within the device driver code segment. A system total 
of 32 timer entry points is available. This timer entry point will be called 
in protect mode each clock tick. 

TickCount helper service is used in the strategy routine to allocate a 
timer entry point within the driver main code segment to be called after 
a fixed number of clock ticks. This service can be used at interrupt time 
to change the number of ticks between calls for an existing timer entry 
point. ResetTimer helper service terminates the timer entry point. 

2.3.6 Device Driver Communication 

Character device drivers may support an inter-device communication 
entry point (IDC entry point). This entry point is described to the in¬ 
itialization loader in the driver header by setting the IDC bit of the device 
attribute word, and by specifying the IDC entry point in the driver header. 

Other drivers must obtain the IDC entry point address to call the IDC 
routine. AttachDD helper service is used to obtain the entry point and 
main data segment address of the IDC driver. 

2.3.7 Character Monitor Management 

Character device monitor support is provided by coordination of the 
application, the device driver, and the monitor dispatcher. The device 
driver accepts requests to open a connection between a monitor chain 
managed by the monitor dispatcher, and the register monitor threads to 
that chain. 

An empty monitor chain is created or deleted with the MonitorCreate 
helper service. The far address of a notification routine and the address 
of a data buffer within the main data segment are arguments to this 
helper service. MonitorCreate must be called in protect mode strategy 
context (and not in interrupt context or real mode). 

A monitor thread is added to a previously created monitor chain by a 
protect mode strategy routine with the Register helper service. The 
Register helper service normally is called in response to the Register 
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Monitor IOCtl. The virtual addresses of the monitor’s input and output 
buffer are arguments to this service. Register is called in ring 0 context. 
A monitor thread may be removed from the monitor chain with De- 
Register. DeRegister is called in ring 0 context. 

A driver-defined character packet (which may be defined to contain 
more than one character) is written to the monitor chain with helper 
service MonWrite. MonWrite may be called in strategy context or in 
interrupt context (real or protect mode). If called in interrupt context and 
no buffer space exists in the monitor chain, MonWrite returns an error. 
If called in ring 0 context with wait option, the thread will block until the 
room exists to write the character to the chain. 

If called in interrupt context and the monitor chain is empty, the 
notification routine will be called in interrupt context (in real or protect 
mode). Otherwise, the notification routine will be called in ring 0 context, 
but in the context of the monitor dispatcher process, not the context of 
the thread that made the MonWrite request. 

The MonFlush service is called to propagate a flush command through 
a monitor chain. MonFlush must be called in protect mode strategy 
context, and will block until the flush is complete. Any MonWrite requests 
issued before the flush completes will block or return errors. 

2.3.8 Queue Management 

Queue management helper services are provided for the convenience of 
the driver writer. These helper services provide management of request 
packets and characters. 

Request packet selectors are tiled, and can be addressed regardless of 
real/protect context. If temporary use of request packets is desired, they 
can be allocated with AllocReqPacket in the strategy routine. If no 
packets are available, the thread will block or optionally return errors. If 
the thread blocks and interrupts are disabled, interrupts will be enabled 
when the thread resumes. Since the number of request packets available 
to the system is limited, any allocated packets should be returned with 
FreeReqPacket as quickly as possible. Allocated packets must not be 
used to return I/O completion status to the operating system. 
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The request packet queue header is a 4-byte pointer contained in the 
device driver main segment. This doubleword is initialized to zero to 
represent the empty queue. Request packets may be added to the request 
packet queue only in strategy context. The packet is added to the tail of 
the queue with PushReqPacket, and in sorted order (ascending starting 
sector number order) with SortReqPacket. These routines do not 
manage the interrupt flag and contention with the interrupt service 
routine must be avoided by the programmer. 

A packet is removed from the head of the queue with PullReqPacket. 
A packet whose address is known may be pulled from the queue with 
PullParticular. PullReqPacket and PullParticular calls can be made 
from either strategy or interrupt context. 

Character queues are circular queues that accept and enqueue single 
characters. The character queue routines disable interrupts as required 
to avoid interrupt routine contention. Character queueing routines are 
callable in strategy or interrupt context. The character queue is allocated 
in the device driver main segment. Six bytes of the header and the buffer 
are allocated as a single structure. The size of the buffer is defined in the 
first word of the queue header. The queue is initialized with the helper 
routine Queuelnit. A single character is written to the queue with 
QueueWrite. Queue Write will return an error if the buffer is full, and 
will not block. 

QueueRead helper service is used to read a single character from the 
queue. QueueRead returns an error if the buffer is empty, and will not 
block. QueueFlush service is used to flush the queue buffer. QueueFlush 
does not block. 

2.3.9 System Services 

Normally, the only system service used is GetDosVar, which obtains 
system specific information. Other services are provided for use by the 
clock device driver, the keyboard device driver, and ROM BIOS support 
in bi-modal devices. These service are extremely specialized in nature, 
and are not discussed here. 

GetDosVar is used to obtain one of the system variables. Each variable 
is associated with an index value, and GetDosVar will obtain the value of 
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that variable. Variables that are available at interrupt time are: the 
address of the global INFO segment, the serial port ownership words, and 
the reboot vector. The global INFO segment contains time-of-day, clock 
tick granularity and other system-global information. 

If GetDosVar is called from strategy context, all interrupt-time vari¬ 
ables are valid, and in addition: the address of the local INFO segment, 
the Yield flag, and the TCYield flag. The local INFO segment contains 
process ID, thread ID, and other information related to the strategy 
routine. 



CHAPTER 3 


DEVICE DRIVER FLOW OF EXECUTION 


3.1 Overview 

A device driver is a piece of software that responds to requests from 
hardware (interrupts) or from the operating system. Each request is 
associated with an entry point within the driver main code segment. 

The device driver should be viewed as an event-driven program. The 
events which start execution are: installation, I/O command, hardware 
interrupt, clock tick, character monitor notification, and inter-device call. 
An event is posted to the driver program by calling the driver entry point 
responsible for handling that event. 

The device driver enters a state based upon the nature of the event that 
took place. For example, receipt of a READ strategy packet by the device 
driver would cause the driver to start the read request to the device 
controller. The driver is now in an "expecting I/O completion" state, where 
it waits for the appropriate hardware interrupts to indicate the data has 
been received. Once the expected data has been received and transferred 
to the READ buffer, the READ strategy routine is unblocked and returns 
to the operating system. The driver is now idle. 
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3.1.1 Installation 

At driver installation time, the operating system has initialized the 
base-line device drivers (the screen, keyboard, mouse, and disk drivers) 
and the file management system. The driver initialization thread, by 
virtue of its responsibility of loading device drivers, must be able to 
manage the global address space and read files from disk. Reading files 
from the disk requires access to the OS/2 API functions, which are 
available only in application context (ring 3 protection level). The global 
^address space, however, can only be accessed in ring 0 protection, or by 
rrffprogr ammin g the global descriptor table (GDT). OS/2 solves this prob¬ 
lem by creating a unique installation context that runs in ring 3 context 
with the GDT programmed for accessibility from ring 3 context. OS/2 
prohibits creation of threads in this context. 

The driver initialization thread reads file CONFIG.SYS, and interprets 
the "DEVICE=" command lines. The file specified in the "DEVTCE=" line 
is a library load module created by the linker in .DLL format. The 
ini ti aliz ation thread opens the file and reads the first segment of the file 
into low memory (below 1M). This segment will be the main data segment 
of the device driver. The second segment of the file is then read into low 
memory. This segment will be the main code segment of the device driver. 
Any additional segments of the file are then read into high memory (above 
1M). 

The initialization thread then attempts to resolve inter-segment refer¬ 
ences. All references to the segments stored in high memory can be 
resolved. No inter-segment references may be made to the main code or 
data segments, .as the values of the selectors used to address these 
se gm ents will change depending on whether the driver is invoked in real 
or protect mode. Exceptions to this rule are single-mode drivers—drivers 
that are known to operate in solely real or protect mode. Real mode-only 
drivers are typically DOS-level drivers, and protect mode-only drivers are 
typically those in OS/2 configurations that do not support the com¬ 
patibility box. 

The initializ ation thread then interprets the device driver header 
located at the start of the main data segment. The device driver header 
includes various information bits used by the file manager, the driver level 
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(DOS vs. OS/2) used by the initialization routine, a link word used by the 
interrupt manager and the initialization thread, the offset in the code 
segment of the strategy routine, and the driver name used by the file 
manager and the initialization thread. 

The initialization thread examines the driver level to determine if this 
driver is to be a DOS-compatible driver that may run only in the com¬ 
patibility box, or an OS/2 driver that may run in either real or protect 
mode. If the driver level is DOS, the initialization thread switches to real 
mode. If the driver level is OS/2, the thread remains in protect mode. The 
initialization thread now formats an INIT packet, places its address in 
ES:BX, and performs a FAR CALL to the main code segment with strategy 
routine offset as specified by the device driver header. 

When the device driver receives control at the strategy routine entry 
point, it interprets the contents of the I/O request packet pointed to by 
ES:BX. If this is an INIT packet, the driver may assume it was called by 
the initialize thread in ring 3 context, and may perform disk I/O, read 
from the keyboard, or write to the screen. 

The initialization strategy routine is responsible for extracting the 
address of the device helper interface from the INIT packet and storing 
that address where it may be accessed later. The initialization strategy 
routine may use the device helper routines, but should take care not to 
suspend the initialization thread inadvertently or it will hang the entire 
system. The initiahze routine typically will allocate memory, obtain IRQ = 
vectors, a nd initializefhe driver hardware. Time-out support and inter¬ 
rupt management support are provided at initialize time. The initialize 
strategy routine terminates by setting completion status in the request 
packet and performing a FAR return (RETF). 

As character device drivers may support multiple devices within a 
single load module, the initialization thread then examines the link 
pointer of the device driver header to determine if this driver manages 
multiple devices. If the link pointer is -l (OFFFFFFFFh), no further 
devices are supported, and the initialize thread returns to reading file 
CONFIG.SYS. If the link pointer points to another device driver header, 
the device driver is called again at the strategy entry point with an INIT 
packet (as described above). Although these pointers are FAR pointers, 
all driver headers are constrained to reside within the main data segment. 
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As the initialization routine loads drivers specified by the "DEVICE=" 
commands contained in the CONFIG.SYS file, the possibility exists that 
a character device driver may be loaded with the same name as some 
previously loaded driver. In this case, the initialization thread is switched 
from ring 3 context to ring 0 context, a DEINSTALL request packet is 
formatted, its address is placed in ES:BX, and the strategy entry point of 
the previously loaded driver with the conflicting name is called. The 
philosophical underpinning of switching to ring 0 context in order to 
service the DEINSTALL request is simply that "all request packets except 
INIT will be serviced at ring 0." No API calls, such as printing a message 
to the screen, may be made during deinstallation. This is an unfortunate 
feature of the initialization architecture. 

When the driver receives control at the strategy routine entry point 
and decodes the DEINSTALL request packet, it decides whether it will 
accept the request. If the driver accepts the request, it must release any 
resources it obtained in response to the INIT packet (IRQs, memory, etc.), 
post a success completion code to the request packet, and return. To reject 
the request, the driver simply posts an error code to the request packet 
and returns. If the request is rej ected, the second driver will not be loaded. 

When the initialization thread has completed installation of all drivers, 
it then releases all extra segments in high memory. The assumption is 
made by the initialization thread that these segments are used only at 
initialization time. This assumption may be overridden by the driver 
writer when linkin g the driver. Each segment that is marked as an IOPL 
segment with the linker SEGMENTS command in the .DEF file, will be 
retained after initialization time. Thus initialization code and data may 
easily be discarded by placement in an extra segment. 

3.1.2 I/O Command 

I/O commands are generated in response to I/O requests by a user-written 
thread. Complex requests such as DosOpen and DosClose are routed to 
the file manager, which operates in protect mode (real mode requests 
cause a mode switch). When such a request is received by the file manager, 
the file manager determines which action to take based upon the nature 
of the request (open, close, etc.), and upon the status bits received by the 
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initialization thread while interpreting device driver header information. 
Once the file manager decides an I/O request is to be forwarded to the 
device driver, the file manager formats a request packet to represent the 
request, places the packet address in ES:BX, and calls the kernel I/O 
system. 

Simpler requests (DosRead, DosDevIOCtl) which can be accomplished 
by a single I/O request to the driver, format a request packet, place its 
address in ES:BX, and call the kernel I/O system. 

The kernel I/O module places the address of the device driver main data 
segment in DS, and makes a FAR CALL to the driver’s strategy rou tin e. 
The strategy routine is called in the real/protect mode context of the user 
thread (protect mode for requests routed through the file manager). If in 
protect mode, entry is made in ring 0, giving the driver access to the global 
address space and the local address space of the calling thread. Note that 
the request packet is tiled, so the same address is valid in either real or 
protect mode. 

The strategy routine (see Figure 3-1) is responsible for interpreting 
request packet contents, performing any required device handling, and 
returning completion and error status. Communication with OS/2 is done 
with the device helper routine, whose address was extracted from the 
INIT request packet by the driver during initialization. 

Once the strategy routine is entered, it cannot be preempted by the 
^scheduler. If a higher priority thread is placed on the scheduler queue, it 
will have to wait until the currently running strategy routine blocks or 
yields. If the strategy routine blocks, it will sleep until awakened by some 
other thread, or until a specified time-out period lapses. If the strategy 
routine yields, it is rescheduled. In either event, any higher priority 
threads are allowed to run. The strategy routine may be interrupted by 
hardware interrupt requests, and must protect against interruption 
during critical sections of code by disabling hardware interrupts (the 
processor CLI instruction)—see Figures 3-2 and 3-3. The strategy routine 
will be blocked if it references unlocked memory that is not present in 
RAM. Status request packets will often be handled immediately by the 
driver strategy routine, which will format and store the required data into 
the request packet. 
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The strategy routine then marks the request packet as done and sets 
any error code in the status word of the request packet. The driver then 
performs a FAR return instruction (RETF) to return to the file manager. 
File manager, read and write I/O requests will often require hardware 
interaction, and will need to perform complex tasks over a period of time. 

In these cases, the strategy routine will often queue the request packet 
on a request queue, and then determine if the device is active. 


Figure 3-1: The Strategy Routine 
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Figure 3-2: Use of CLI and STI to Protect Against Interrupts 
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Figure 3-3: Use of CLI and STI to Protect Against Interrupts 
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If the device is idle, the strategy routine will start I/O to the device, and 
then typically block itself. The strategy routine may block itself in two 
ways—with the 'device-helper-routine~Block, or by performing a FAR 
return without having set the completion status in the request packet. 

If Block is used, the strategy routine resumes when another context 
issues a Run device helper service against the strategy thread, or when 
a time-out period lapses. If the strategy routine returns without having 
set request packet completion status, it is suspended by the operating 
system, and a thread in another context must post completion information 
to the request packet and unblock the strategy thread using the device 
helper service DevDone. 

An interrupt-driven device driver will normally be entered after a 
period of time at the interrupt entry point in response to a device interrupt 
request. Several interrupts may be required to service the I/O request. 
Once the I/O request has been serviced by the device, the interrupt routine 
dequeues the request packet, sets the request packet completion status, 
and unblocks the strategy routine. See Figure 3-4 for a summary of the 
interrupt routine. The strategy routine is scheduled, and will then run to 
completion. 

A good example of a critical code section in the strategy routine is that 
code which enqueues the strategy packet. If the strategy routine was 
interrupted while in the process of enqueueing its strategy packet and 
the interrupt routine attempted to dequeue a packet in the same queue, 
unpredictable results would occur. The strategy routine should execute a 
processor CLI instruction before attempting to examine or modify the 
queue. 

A polled device driver may use several different blocking strategies, 
depending upon the speed of the device. Low speed devices may block with 
a short time-out period, or process the device using a clock tick entry point. 
The clock granularity (on the AT and PS/2) is 31.25 milliseconds, so the 
device will be handled only 32 times per second with this technique. 
Faster devices can be handled by examining the device registers, and if 
the device is not ready, yielding control to other processes. Only higher or 
equal priority processes will run in this case, and the amount of time the 
device will have to wait is unpredictable. In general, polling is discouraged 
under OS/2. 
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Figure 3-4: The Interrupt Service Routine 
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3.1.3 Hardware Interrupt 

The strategy routine (or initialize routine) normally will issue the SetIRQ 
device helper routine to establish an association between the hardware 
interrupt (IRQ) level generated by the programmable interrupt controller 
(PIC), and an entry point within the device driver main code segment. 
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The device controller requests interrupt service from the PIC, contending 
with other controllers that may be requesting interrupts and possibly 
contending with devices sharing the same interrupt level. The PIC 
arbitrates between contending requests, and issues an interrupt request 
to the processor. When the processor acknowledges the request, the PIC 
sends the IRQ level of the highest priority request to the processor. 

Control is now passed to the interrupt manager, that saves all registers. 
The interrupt manager then determines the first driver which has estab¬ 
lished an entry point for this IRQ level and determines the current 
processor mode (real/protect). The interrupt manager (see Figure 3-5) sets 
CS and DS to the proper values for this driver in the current real/ protect 
context, and performs a FAR CALL to the interrupt entry point. 

The interrupt service routine receives control at the interrupt entry 
point established in the initialization or strategy routines (helper service 
SetIRQ). This routine will perform any necessary device control including 
dismissal of the interrupt request at the device controller, and will-clear 
the IRQ level of the PIC (using the device helper routine E01). Several 
^physical devices that share the same controller-may be handled in this 
way. 

Once the interrupt request has been dismissed at the PIC, the interrupt 
service routine can be interrupted at its own entiy point. The interrupt 
service routine disables interrupts to exclude this possibility. The inter¬ 
rupt service routine is entered with interrupts disabled if the IRQ level 
is exclusively owned. Interrupts are enabled at entry to interrupt service 
routines that share IRQs (to reduce interrupt latency). 

Some device I/O operations require several interrupts. In this the case, 
the interrupt routine indicates it has serviced the interrupt (by clearing 
the cany bit), and returns to the interrupt handler. Spurious device 
interrupts are also handled by clearing the device controller interrupt 
request, clearing the PIC, and returning to the interrupt handler having 
indicated service of the interrupt by clearing the carry bit. 

On AT machines that have edge-sensitive operations of the PIC, the 
EOI is issued before clearing the device controller, guaranteeing that no 
interrupts will be lost from the device. On the PS/2, where the PIC is 
level-sensitive, the controller must be cleared before issuing the EOI in 
order to prevent multiple acknowledgments of a single interrupt request. 
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In the case of device sharing (supported on PS/2 but not AT), each driver 
called by the interrupt manager determines whether the interrupt was 
generated by its device controller. The driver clears the carry flag to 
indicate it has serviced the interrupt, and sets it if it has not. If carry is 
set, the interrupt handler passes the interrupt onto the next driver. 

If this interrupt has resulted in completion of the I/O request, the 
interrupt routine typically sets completion status in the request packet, 
and unblocks the waiting thread (using device helper routines Run or 
DevDone). The waiting thread is rescheduled, and will run at the next 
opportunity. 

The interrupt routine will then normally dequeue the next waiting 
strategy packet, and initiate I/O on its behalf. Finally, the interrupt 
service routine clears the carry flag to indicate interrupt service, and 
returns to the interrupt manager. When the interrupt manager receives 
notification of service by the interrupt routine (the carry bit was clear 
before return), the interrupt manager restores all registers and performs 
a processor return from interrupt (IRET) instruction to resume the 
interrupted context. 

3.1.4 Clock Tick 

The strategy or initialization routines may specify a timer entry point 
within the main code segment. The entry point may be specified to be 
called every one or more clock ticks. The timer routine is entered in protect 
mode. 

IRQ 8 is specified on the PS/2 and AT to be generated by the real-time 
clock every 31.25 milliseconds. The system clock handler receives the 
clock tick interrupt and looks for all timer entry points to be called (a 
system ■maximum'ofi32 i timer entry-points4s examined). Each entry point 
that is to intercept the clock tick is called by the timer handler in turn. 

The timer routine establishes CS and DS to address the main code and 
data segments of the driver to be called and performs a FAR CALL to the 
timer routine entry point. The timer routine is required to preserve all 
registers, including segment registers DS and ES. The timer routine 
returns to the clock tick handler with a RETF instruction. The clock tick 
handler then calls the next timer routine in the list of timer entry points. 
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The timer routine may be used for polling slow devices, as it uses very 
little overhead. It may also be useful for device time-out. See Figure 3-8 
for a look at a timer interrupt. 

3.1.5 Character Monitor 

A character device can support monitor chains. Each monitor chain is 
maintained by the operating system in response to I/O request packets or 
an internal driver-defined event. 

3.1.5.1 Monitor Chain Creation At initialize time, the driver may 
pre-allocate monitor chains for later use. Typical driver applications 
allocate a single monitor chain, a driver-defined number of chains, one 
chain per served screen group, or one chain per process. In the single chain 
case or driver-defined cases, pre-allocation is probably indicated; and the 
c hain per screen group case may be best handled by pre-allocating all 12 
possible chains. In the one chain per process case, allocation at application 
time is probably indicated. For process management reasons, the one 
chain per process technique is often preferred. 

When an application issues the API call DosMonOpen, the file system 
converts the request to an OPEN request packet with the MON bit set in 
the status word. The driver decides whether the monitor chain exists, and 
if not, creates that chain. The process ID and screen group are found in 
the local INFO segment, returned by the GetDOSVar device helper 
function. The monitor chain is created with the device helper call Mon- 
Create. An empty monitor chain is created, and associated with a final 
buffer and a notification routine, both of which are specified by the 
device driver. 

3.1.5.2 Register Monitor Thread When a process issues the API call 
DosMonReg, the effect is to issue a category OAh, function 40h, generic 
IOCtl call. The strategy routine is then required to add the monitor thread 
to the appropriate monitor chain, using the device helper routine Register. 

Each monitor thread is associated with an input buffer, an output 
buffer, a chain position, and a driver-defined chain index. This informa¬ 
tion is co mmuni cated to the driver. The driver selects the chain on which 
the thread is to be registered, based upon screen group, process ID, or 
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chain index. The screen group and process ID are obtainable from the 
local INFO segment returned by the GetDOSVar device helper routine. 

The Register device helper routine adds the monitor thread to the 
appropriate chain, associating the thread with the process ID of the 
calling process. 

3.1.5.3 Dispatch Character to Monitor Chain Characters may be 
received from a WRITE request packet, or as input from the device. 
Characters received from a WRITE request packet are packaged in a 
device-dependent monitor character packet, and are written to the 
monitor chain in strategy context. The MonWrite device helper function 
is used to write this packet to the monitor chain. If the buffers of the 
monitor chain are full, the driver writer may request the MonWrite 
routine to wait until the write is complete, or to return immediately with 
an error. 

When monitor threads on the monitor chain have completed processing 
of the character packet, the notification routine is called in ring 0 context 
(but not strategy context). The notification routine performs the functions 
normally performed by the strategy routine in response to a WRITE 
request (queue the strategy WRITE packet and start hardware I/O). 

A character received from a device is normally received in interrupt 
context—see Figures 3-6 and 3-7. This character is packaged in a device¬ 
dependent monitor packet, and written to the appropriate monitor chain. 
If the buffers of the chain are full, the MonWrite call returns with error. 
The MonWrite helper routine can not wait in interrupt context. The 
interrupt routine then reenables the device controller to accept the next 
interrupt. 

When all monitor threads on the monitor chain have completed process¬ 
ing of the character, the notification routine is called in ring 0 context. If 
the monitor chain is empty, the notification routine will be called in 
interrupt context. The notification routine performs the functions of 
system coordination normally performed by the interrupt routine (adding 
characters to the input queue, marking READ request packet complete, 
unblocking the strategy routine). 
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3.1.5.4 Notification Routine The notification routine is called by the 
monitor dispatcher when a character packet has been placed in the final 
buffer, and is available for processing by the driver. The notification 
routine is normally called in a ring 0 context reserved for use by the 
monitor dispatcher, and not in the strategy context that initiated the I/O. 

In the case that a character packet was written to the monitor chain in 
interrupt context and the monitor chain was empty, the notification 
routine would be called in interrupt context. For this reason, a notification 
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routine should be carefully written if it will request suspension or if it 
uses other ring 0 features. 

Usually, a separate monitor chain will be assigned for use for characters 
written to the device and for characters read from the device. 

The no tifi cation routine that receives characters destined to be written 
to the device will normally perform the interrupt functions associated 
with that request. These actions include queueing the request packet to 
the output queue and starting device I/O if the device is idle. 

The notification routine that receives characters destined to satisfy a 
READ strategy request collects these characters in a character queue. 
When the READ request is satisfied, the notification routine removes the 
READ request packet from the queue, marks the I/O operation as com¬ 
plete, and unblocks the strategy thread that made the request. The 
notification routine functions similarly to an interrupt routine, except 
that device management would be performed by the interrupt routine. 

3.1.5.5 Flush Monitor Chain A monitor chain is flushed by the device 
driver in response to strategy packet INPUT FLUSH and OUTPUT 
FLUSH, IOCtl category OBh, function 1 (Flush Input Buffer) or IOCtl 
category OBh, function 2 (Flush Output Buffer). The appropriate chains 
are selected by the device driver and the driver executes a MonFlush 
device helper request for each chain. MonFlush waits until all characters 
in the selected chain have been discarded, and must therefore be used 
only in ring 0 context. The character queues are also flushed by the driver, 
and pending request packets are returned with error. 

3.1.5.6 Deregister Monitor Thread If a process containing monitor 
threads terminates or issues a DosMonClose API call, the driver receives 
a CLOSE strategy packet with the MON bit of the status word set. The 
device driver must flush chains containing monitors for this process, and 
then must deregister monitor threads belonging to the process. 

The device driver issues the MonFlush device helper routine to flush 
all characters in the chain, thereby bringing the chain to a known state. 
Once flushed, all threads on the chain belonging to the terminating 
process are deregistered with a call to the DeRegister device helper 
routine. If the chain was allocated on a per-process basis, the driver may 
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then delete the chain with the MonCreate device helper routine (which 
was originally called to create the chain). 

3.2 Initialization Mode Routines 

Initialization mode is called by the OS/2 kernel in ring 3 protect mode, 
allowing the driver writer to use API calls in addition to the standard 
device helper routines. 

Devices whose headers specify that they are DOS (real mode-only) 
devices are initialized in real mode instead of protect mode. These drivers 
can be called only from the compatibility box, and must operate only in 
the compatibility box. Interrupt-driven devices would normally be ex¬ 
cluded, since they may receive interrupts after the user has switched to 
a protect mode session. 

Deinstallation may be required in certain cases. A character device 
driver is deinstalled if an attempt is made to install a subsequent driver 
of the same name. An unfortunate quirk of OS/2 is that deinstallation 
occurs at ring 0, and thus API calls are not available (to write a message 
to the screen, for example). 

Device driver writers must be particularly aware of the fact that their 
strategy and interrupt routines are callable in either protect or real mode. 
Some system-provided addresses are tiled or bi-modal, which, for 
device driver writers, include the address of the device helper routines 
and the address of the strategy packet. All other addresses are sensitive 
to the hardware context. Note that the driver main data segment and 
main code segment are not bi-modal. 

Extra data and code segments may be loaded at initialize time. Only 
■the main code and data segments are -loaded~into~low~ memory All 
additional-segments are loaded into high memory. Extra-segments that 
care needed after initialize-time must-be marked_as-IOPL segments at link 
time (using the SEGMENTS directive in the .DEF file). All segments not 
so marked-will be-discarded after initialize time. 

OS/2 provides device helper routines callable from assembly language 
programs. The tiled address of the helper interface is passed to the driver 
at initialization time. Subsequent calls made to this address contain the 
device helper code in register DL. 
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At initializ e time the address of the device helper interface is extracted 
from the EMIT packet. The primary functions of a typical initialization 
routine will include interrupt vector management, memory allocation, 
creation of a monitor chain (character devices only), and timer manage¬ 
ment (typically used for polled devices). Also at initialize time, the driver 
is called at the strategy routine entry point with ES:BX pointing to the 
EMIT packet. The (far) address of the device helper interface is located at 
an offset of 14 bytes into the packet. The following code might be used to 
extract the address and place it in location DevHlp: 


MOV 

AX,word ptr ES:[BX+14] 

offset word of address 

MOV 

word ptr DevHlp,AX 


MOV 

AX,word ptr ES:[BX+16] 

segment word of address 

MOV 

word ptr DevHlp+2,AX 



The device helper routines are invoked by setting 
required register values, placing the device hel¬ 
per function code in DL, and calling the DevHlp 
entry point. 

MOV DL, function code 

CALL dword ptr [DevHlp] 


3.2.1 API Calls Available at Initialize Time 

The initializ e routine is called at ring 3 in protect mode for OS/2 device 
drivers, and in real mode for DOS device drivers. API calls are available 
for use of OS/2 device drivers. 

At entry to the device driver, OS/2 has initialized the file management 
system and all base-line devices. All devices fisted in CONFIG.SYS file 
before the current device have also been initialized. API calls to perform 
I/O to these devices are permitted. 

Process management API calls are not permitted. The context of the 
initialize protect mode process is ring 3 with access to global address 
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space. The process cannot be spawned without jeopardizing the memory 
protection scheme. Process management is not supported for the com¬ 
patibility box. 

Memory management API calls are not permitted. These calls would 
allocate memory in the context of the initialize process. Use device helper 
routines for memory management. The following API calls are available 
at initialize time: 


File I/O: 

DosOpen 

DosRead 

DosWrite 

DosChgFPtr 

DosClose 

DosDevIOCtl 


Open a file 
Read from a file 
Write to a file 

Randomly reposition file pointer 
Close a file 

Perform generic I/O control functions to a driver 


Directory Management: 


DosFindFirst 

DosFindNext 

DosFindClose 

DosDelete 


Look for a file, using pattern match 
Look for next file matching pattern 
Terminate pattern match search 
Delete a file 


File System Information: 


DosDevConfig 

DosQCurDir 

DosQCurDisk 

DosQFilelnfo 

DosQFileMode 


Get system configuration (number of printers, etc:) 

Get current working directory 

Get current working disk 

Get file status (creation date, etc.) 

Get file attribute bits 


System Message Handling: 

DosGetMessage Retrieves message from system message file 
DosPutMessage Writes message out 

Base-Line I/O: 


DosBeep 


Produces audible signal 


3.2.2 Interrupt Management at Initialize Time 

Atypical device driver will acquire an interrupt vector, associating it with 
an entry point within the driver. The driver may clear the interrupt 
controller after acquiring the interrupt vector. 
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All~interrupts- must--share _ the _ s'ame" stack. This size of the stack 
requirements for a device are specified at initialize time. The system total 
stack requirements are computed, and are constrained by the system to 
jBK. Stack requirements are computed with the device helper routine 
RegisterStackUsage. Qaleulation-of^stack^requirements^includes ^al- 
dowance for-uninterruptable code - sections and- “nested’ ? codesections 
(sections that are able to interrupt themselves, leading to greater stack 
utilization). 

Hardware interrupts are intercepted with SetIRQ which is a device-in- 
dependent means of managing hardware interrupts. The initialization 
code associates a hardware interrupt request with an interrupt service 
routine within the main code segment. The interrupt level of the program¬ 
mable interrupt controller may be cleared at initialize time with device 
helper routine EOI—after the interrupt service routine has terminated. 

3.2.3 Memory Management at Initialize Time 

At init i aliz e time, a typical device driver can allocate a block of memory, 
map its address to a selector, and access that memory. The driver is 
required to release process local mapping selectors before returning from 
the initialize routine. Device helper routine, AllocPhys is used to allocate 
physical memory. All memory addresses are normally stored by the driver 
as physical addresses and are mapped when needed. This is to minimize 
the impact of possible real/protect context switches. Several mapping 
mechanisms are available for use. 

Mapping of memory may be done locally with PhysToVirt or 
PhysToUVirt. PhysToVirt allows a maximum of two addresses to be 
mapped simultaneously, but functions in any context. PhysToUVirt al¬ 
lows an almost unlimited number of simultaneous mappings (up to 8,192 
per process), but functions only in protect mode and creates the mapping 
selectors in the installation thread context, which will not be accessible 
after installation is complete. 

Global selectors may be permanently allocated to the driver using 
AllocGDTSelector and global mapping is performed with 
PhysToGDTSelector. Once they are mapped, the selectors are accessed in 
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protect mode regardless of the underlying process. The selectors cannot 
be accessed in real mode. 

3.2.4 Timer Management at Initialize Time 

One or more timer entry points may be defined for a device driver. This 
entry point is called every clock tick (SetTimer), or every n clock ticks 
(TickCount). The timer entry point would normally be used in handling 
(slow) polled devices, and may also be used for device tim ers. En try will 
be made at the timer entry point with interrupts enabled. The driver 
executes a far return instruction (RETF) to dismiss the timer tick. 
Processing must be extremely quick and all registers must be preserved. 

Clock ticks are registered each 31.25 milliseconds (32 ticks per second) 
on the AT and PS/2. A system maximum of 32 timer handles is provided. 

3.2.5 Creating a Character Monitor at Initialize Time 

A character device may support one or more monitor chains; that is, a 
fist of monitor threads. A character is written at strategy or interrupt tim e 
to the monitor chain, and is successively passed to each monitor thread 
in the chain by the monitor dispatcher. Each monitor thread in the 
chain receives the data, processes it in task context, and then writes the 
data to back to the monitor chain, at which time it is transferred to the 
next monitor. 

When the monitor chain is exhausted, the data is written to the final 
buffer provided by the device driver, and a driver-provided notification 
routine is called to complete processing of the data. The notification 
routine is called in the context of the monitor dispatcher or in the context 
of the thread that writes the character to the monitor chain if the chain 
is empty. The notification routine is called in protect mode with DS set to 
the driver main data segment, and with ES:SI pointing to the final buffer 
within the main data segment containing the processed data. The 
notification routine should be written to function in both ring 0 and 
interrupt context. 
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3.2.6 Accessing DOS Variables at Initialization Time 

Information concerning OS/2 configuration is accessible in a dual-mode 
selector/segment address. This address may be obtained at initialize time 
and used at either initialize or interrupt time. 

Variables that can be accessed at initialize time are limited to the global 
INFO segment, the COM ports, and the reboot vector (see Figure 3-9). 

The ,global I NFO-segment contains data global to OS/2, such as 
date/time, clock tick resolution, and OS/2 version number. The local INFO 
segment is also addressable, but contains data local to the initialize 
process only. 

Figure 3-9: Getting DOS Variables_ 
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The COM ports are made available in order to register ownership of 
the COM devices COM1 and COM2 to a particular process. If a port is 0, 
no other process can obtain ownership of that COM device. This is a way 
of sharing ownership of COM hardware across device drivers (i.e., the 
mouse might need a port). The reboot vector probably should not be used, 
as it gives the user no opportunity to correct the underlying fault. 

3.2.7 Communication Between Drivers 

The initialize routine may set up a link to another device driver. This link 
is established with a previously initialized driver that supports inter¬ 
device driver communication (IDC) with the AttachDD helper service. 
AttachDD returns the CSroffset of the IDC entry point, and the DS of the 
driver. Both real and protect mode CS and DS are returned. 

The context in which the IDC call is made (real/protect, strategy/inter¬ 
rupt) and the interpretation of registers other than CS and DS, are 
determined by cooperation of the device drivers. Any device driver that 
accepts IDC link requests must be a character device driver, and have 
the IDC bit set in the device header word at ini tialize tim e. 

3.3 Strategy Routines 

I/O request packets are formatted by an API call or the file manager, then 
passed through the kernel I/O manager to the device driver strategy 
routine. If the kernel was called from a protect mode application or the 
file manager, the strategy routine is entered in ring 0 protect mode, with 
the local address space of the calling process. If the kernel was called by 
the compatibility box, the strategy routine is entered in real mode. 

Typical device drivers are callable from either protect mode applica¬ 
tions or the compatibility box. The strategy routine of these drivers must 
be capable of functioning in either context. The strategy routine is called 
with the correct values of CS and DS for the main driver segments for the 
appropriate real/protect mode context (see Figure 3-10), and is passed a 
tiled strategy packet address that is valid in either context. 

Strategy packets are really the means by which the application and the 
file manager communicate with the device driver. Three main l/O models 
are supported: block devices, character devices, and generic I/O control. 
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Block devices are random access devices that support logical units, 
removable media, and a directory structure. These devices have a com¬ 
plex, but well-defined interface to the file manager. Character devices 
have a simpler, less well-defined, but more flexible interface to the 
application and the file management system. 

Character devices are normally used to support any function that falls 
outside the block driver model. A third, completely user-defined model 
exists—the generic I/O control model (IOCtl). 


Figure 3-10: Registers at Entry to Strategy Routine 
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The IOCtl interface passes a strategy packet to the kernel VO manager 
whose contents are interpreted according to standards established by the 
driver itself. 

3.3.1 Block Devices 

The block device model is built upon a single physical drive consisting of 
a collection of fixed-length sectors (see Figures 3-11 and 3-12). The sectors 
are collected into fixed-length units called tracks, and tracks are again 
collected into fixed-length units called cylinders. The number of tracks 
collected into a cylinder is called the number of heads. 


Figure 3-11; Format of Physical Drive with 4 Heads and 5 Sectors 
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This physical drive may then be partitioned by the driver into logical 
units. Each unit now contains a separate and complete file system 
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managed by the file manager. Each unit is assigned a one-letter name at 
ins t allat ion time (A:, B:, etc.). These names are assigned in sequence as 
the device drivers are loaded. 

Physical disk control is provided with reserved (category 9) IOCtl 
packets (see Figure 3-13), which would normally be used only by special- 
purpose programs (i.e., low-level format and disk partition). Category 9 
IOCtl packets include Get Physical Device Characteristics, Lock Physical 
Drive, Unlock Physical Drive, Write Physical Track, Read Physical Track, 
and Verify Physical Track. A handle for use with category 9 IOCTL calls 
to a physical device is obtained by issuing API call DosPhysicalDisk. 

Figure 3-12: Logical Sector Number Sequence_ 
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Figure 3-13: Flow of I/O Requests into Block Drive 
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The low-level format program will typically obtain the device charac¬ 
teristics, lock the physical drive, write and verify tracks, write a bad-block 
table, and unlock the physical drive. The bad-block table must be inter¬ 
pretable by the device driver, as no file management support is provided 
for this function. 

The disk partition program will partition the physical media into 
logical uni ts by locking the physical drive, writing partition information, 
and unlocking the drive. The device driver must be able to access this 
inf ormation and format it for use by the file manager. 

Logical disk and removable media control is provided with reserved 
(category 8) IOCtl packets, which would normally be used only by special- 
purpose programs (i.e., high-level format). Category 8 IOCtl packets 
include Get/Set Device Parameters, Queiy Removable Flag, Redetermine 
Media, Lock/Unlock Drive, Write Track, Read Track, Verify Track, and 
Format Track. 

Much of the Category 8 IOCtl functionality is duplicated in strategy 
packets issued by the file manager. Strategy packet BUILD BPB repli¬ 
cates the functionality of Get Device Parameters, REMOVABLE MEDIA 
reproduces the Query Removable Flag function, and RESET MEDIA has 
the same effect as Redetermine Media. 

The high-level format program would typically open a DASD file to the 
logical unit (DosOpen API call), lock the logical unit, get the unit 
parameters, issue format requests for each track, write the FAT and root 
directory, and unlock the drive. 

The file manager queries the removable state of the unit flag. If the 
media is removable, the file manager will determine the media, and get 
the unit parameters. The file manager then issues its normal READ and 
WRITE strategy request packets. After the media has been changed, the 
driver returns the error "Uncertain Media" to all file manager requests. 
The file manager will redetermine the media and get the unit parameters 
when it receives this error. 

The file manager will correctly handle removable media only if the OPN 
bit was set in the device driver header attribute word (DAW) at initialize 
time. File management functions are supported by the strategy packets 
OPEN, READ, WRITE, WRITE/VERIFY, and CLOSE. 
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3.3.1.1 Physical Drive Control A special-purpose program may re¬ 
quire the block driver to support physical I/O. Prototypical programs are 
the low-level format program and the disk partitioning program (see 
Figure 3-14). 

Low Level Format: The low-level format program issues the DosPhysical- 
Disk API to obtain a handle to the selected physical device. This handle 
is valid for use with Category 9 IOCtl calls only. The program will now 
use the IOCtl interface for further processing of the physical device. 


Figure 3-14: Partitioned Drive Layout (see Appendix E for details) 
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The IOCtl call, Get Physical Device Characteristics, may be used to 
request the physical characteristics of the device—the number of heads, 
tracks per head (cylinders), and number of sectors per track. Sectors are 
typically 512 bytes in length. 

The next step is reserving the physical device for exclusive use of the 
program. The IOCtl packet, Lock Physical Drive, is sent to the device 
driver strategy routine to request lock of the entire physical device. This 
lock will be denied if there is a pending lock on any of the logical units, or 
if files are open to any of the logical units. 

The format program is now free to issue Physical Read Track, Physical 
Write Track, or Physical Verify Track IOCtl calls to the driver. Included 
in these calls is the starting sector position (head, cylinder, and sector 
number), the number of sectors to read, and a track layout table. These 
calls will process sectors only within a single track, and are not permitted 
to change cylinder or head. The track layout table contains the sequence 
in which sectors are laid out on the track. The sequence of sectors within 
a track is defined by the calling program, and is used to minimize 
rotational latency of hard disks when accessing sectors in logical sequen¬ 
tial order. 

The low-level format program might write and verify each track, and 
also keep a record of the bad sectors. The program might reserve several 
tracks for the error table. The driver would read the error table at 
initialize time and return error for references to bad sectors. By conven¬ 
tion, the error table is allocated at the end of the disk. 

The program must release the physical media with the IOCtl call, 
Unlock Physical Drive. The program should finally release its handle to 
the physical disk with the API call, DosPhysicalDisk. 

Disk Partitioning Software: The disk partitioning program first decides 
which physical drive is to be partitioned into logical units. At initialize 
time, the file manager calls each block device driver strategy routine with 
packet PARTITIONABLE FIXED DISKS. Each device driver is expected 
to return the count of physical drives it supports in response to this call. 
The file manager returns the system total number of physical drives to 
the partitioning program in response to the DosPhysicalDisk API. 
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The sequence of events issued by the drive partitioning program to 
create the logical unit partition on the physical drive is similar to that 
issued by the low-level format program. A handle to the physical drive is 
obtained (with DosPhysicalDisk), the physical drive is locked (IOCtl call 
LockPhysical Drive), and the partition track is written. This track will be 
interpreted by the device driver at initialize time in order to determine 
how many logical units it supports and also the size and configuration of 
each logical unit—see Figure 3-14. 

Since the number and configuration of logical units has changed, the 
drive partition program should reboot the system. 

3.3.1.2 Logical Unit Control Logical unit control is provided primarily 
for high-level formatting purposes. A disk partition program may be 
written to subdivide the physical disks into logical units. This subdivision 
information is interpreted by the device driver. When the device driver is 
installed, it returns the number of logical units it will control to the file 
manager. The high-level format program initializes the file allocation 
table and directory of each logical unit. 

I 

/ 

File Manager Support: The file manager may require information 
regarding which logical units are supported on which physical drive. The 
file manager would issue the GET PHYSICAL DISK/LOGICAL UNIT 
MAP strategy packet to the driver strategy routine. Upon receipt of this 
packet, the driver is expected to return a bit map of all logical units 
associated with the physical drive (specified in the strategy packet logical 
unit number field). 

The file manager issues only one other strategy packet in this context: 
BUILD BPB. The driver returns the BIOS Parameter Block containing 
logical unit size and configuration data. . 

Format Program Support: The high-level format program will use 
Category 8 IOCtl calls to perform its functions. The file system handle for 
these calls is returned from the API call, DosOpen, with the DASD open 
mode selected. 

The file allocation table and directory must be written conforming to 
the format expected by the file manager. The size of the file allocation 
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table, the directory, and the starting sector of the logical unit within the 
physical disk, are specified in a structure called the BIOS Parameter 
Block (BPB). The BPB is passed to the program in response to its request 
to the device driver for device parameters (IOCtl call, GetDeviceParams). 

A high-level format program will then use the device parameters to 
determine the size of the device. The program would then lock the logical 
unit (IOCtl call, LockDrive). The file manager will allow this lock only if 
there was no previous physical drive lock, and there are no files open to 
this logical unit. 

Once locked, the high-level format program would typically write the 
file allocation table and the root directory (IOCtl call WriteTrack followed 
by IOCtl call VerifyTrack). The program might then format and verify 
each track with the IOCtl call, Format Verify. Each bad sector would be 
marked in the file allocation table. 

When complete, the program releases the logical unit with IOCtl call, 
UnLockDrive. The program should then release its unit handle. 

3.3.1.3 Removable Media Support Removable media is supported 
under OS/2 for both application programs and the file manager. Program 
support for removable media is provided by IOCtl calls, and file manager 
support is provided by means of strategy packets. 

The driver must determine if the media has been removed. Some 
devices report a changeline status to the driver when the media is 
changed, but many do not. Those devices that do not report media change, 
may check volume labels or simply wait for a time-out period to lapse 
(normally 2 seconds). 

File Manager Support: The file manager is informed by the device header 
attribute word that the media is removable. The file manager may 
supplement this knowledge by issuing a REMOVABLE MEDIA packet to 
the device driver. The device driver returns the status of the media for 
the requested logical unit—removable/fixed. 

The file manager issues the MEDIA CHECK request packet to the 
device driver before altering the directory or file allocation table. The 
device driver determines if the media has been changed, and sets a return 
code (not error status) to reflect the change state. If changed, the driver 
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may return the volume ID of the previous media, allowing the file 
manager to prompt for the correct media. 

If the driver uses the BIOS Parameter Block to describe media type 
(instead of the media attribute word returned by MEDIA CHECK), the 
IBM bit of the device attribute word should be set (normal case for DOS 
file formats after 2.0). 

Once the file manager has taken the necessary corrective action after 
being informed of a media change by the device driver, the RESET MEDIA 
packet is sent to the driver to cause the new media to be registered as 
current by the device driver. Only after receiving this packet may the 
driver allow I/O to the media. 

Special support for multiple-density drives is provided with the BUILD 
BPB strategy packet. This packet will be sent, by the file manager, to the 
driver following the RESET MEDIA packet. The driver returns a BPB for 
the media that is in the drive. 

Application Program Support: An application that handles removable 
media will use Category 8 IOCtl calls to perform its functions. The file 
system handle for these calls is returned from the API call, DosOpen, with 
the DASD open mode selected. 

The IOCtl command, ReDetermineMedia, may be issued to cause the 
driver to determine the current disk. All volume ID processing, if any, is 
done internal to the device driver. The program becomes aware of the 
indeterminate state of the media through a returned error code from other 
I/O operations. 

The GetDeviceParameters IOCtl call is used to obtain the current 
BIOS parameter block, or the recommended. BIOS parameter block. The 
current BPB contains the media characteristics for the current media. 
These characteristics can change for removable devices that feature 
multiple-density support. The program should issue GetDevice¬ 
Parameters after ReDetermineMedia. 

SetDeviceParameters may be used to change the current BPB. This 
might be useful to a program that wishes to write low-density information 
to high-density media. 
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3.3.1.5 File I/O The file I/O model under OS/2 is driven by the file 
manager and is .composed of only five strategy packets: OPEN, READ, 
WRITE, WRITE/VERIFY, and CLOSE. 

When the application issues the API call, DosOpen, the file manager 
determines if a physical or logical unit lock is pending and refuses the 
request if so. Otherwise, the file manager issues the OPEN strategy 
packet to the device driver. The request packet CLOSE is issued by the 
file manager in response to API call, DosClose. 

The READ request packet is used to transfer data from the logical unit 
to memory, and the WRITE request is used to transfer data from memory 
to the device. If supported by the device driver, WRITE/VERIFY requires 
the driver to write data from memoiy to the device, and then to verify the 
integrity of the data on the media (by reading the data back in and 
comparing it to the buffer contents). Data is transferred to or from the 
media in sectors. 

3.3.2 Character Devices 

Character devices support simpler structures than block devices in that 
no directory structure exists on a character device. Character-device 
drivers aremamed with-eight-charactermames-that are known to the file 
system (block drivers are named sequentially A: to Z:). Streams of char¬ 
acters written to that filename are written to the character device (not to 
a file or any block device) and, conversely, reads from that filename are 
drawn from the character device driver. 

The input or output character stream may be monitored by threads of 
a process. The classic example of such monitoring is a DOS terminate- 
and-stay-resident program (TSR) that examines raw keyboard data 
before forwarding it to the KBD: driver. This function is formalized in 
OS/2 character device drivers (monitoring). 

3.3.2.1 Deinstallation Before a character device is initialized, OS/2 
checks to determine whether any character devices of the same name 
have already been loaded. If a driver of the same name has been loaded 
by the initialize process, OS/2 attempts to deinstall the previous driver 
by sending a DEINSTALL packet to the strategy routine (in ring 0 context 
for OS/2 drivers, and in real mode for DOS drivers). 
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The driver targeted for deinstallation may refuse to deinstall by setting 
the error "Unknown Command" in the status word of the DEINSTALL 
strategy packet. The second driver will not be installed in this case. 

If the driver elects to deinstall, it should release all resources allocated 
at install time. Particularly, the driver should release all physical 
memory, all IRQ interrupt vectors, and any global selectors. 

3.3.2.2 File I/O Character file I/O is composed of Device OPEN, Device 
CLOSE, READ, NONDESTRUCTIVE READ NO WAIT, and WRITE 
strategy packets. 

Device OPEN is issued in response to the API call, DosOpen. The device 
driver will ordinarily grant ownership of a character device to a single 
process, and so will allow only one process to open a file to the device at 
any one time. The character device driver, however, would normally allow 
multiple files to be open to the same device from one process. The driver 
would keep an open count for the current owning process, and decrement 
the count for each Device CLOSE issued to the driver from the same 
process (API call, DosClose). When the count returns to zero, the device 
is available for the next requesting process. Any character driver that 
supports the OPEN and CLOSE packets should have the OPN bit set in 
its device header word at initialize time. If the file manager sharing rules 
are to be used for arbitration of device ownership (instead of internal open 
logic), the driver header bit SHR should be set. 

If an open request is issued to the device from a process while another 
process owns the device, the driver must decide whether to hold the 
Device OPEN packet for later processing or to return the packet immedi¬ 
ately with an error. 

When a READ request is received, the driver obtains a physical buffer 
address and length from the strategy packet. The driver then attempts 
to service this request by returning a (driver-defined) logical record. If the 
driver supports reading from the device ahead of file manager requests, 
these buffered characters are used to service the request. If insufficient 
characters have been buffered by the driver, the strategy thread is blocked 
waiting for the device. When the driver determines that the READ 
request has been satisfied, the driver returns character count and com- 
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pletion status in the READ packet. A returned character count of zero will 
be interpreted to represent the end-of-file condition. 

The WRITE request is serviced by the driver by obtaining a physical 
buffer address and character count from the request packet. If the driver 
supports buffering of output characters, characters are written from the 
physical buffer to the output queue. If insufficient room exists in the 
queue to service the entire request, or if the driver does not support output 
buffering, the strategy thread is blocked while waiting for the device to 
service the request. When the WRITE request has been serviced, the 
driver places a count of characters written and completion status in the 
WRITE packet. A returned character count not equal to the requested 
count will be interpreted as an error condition. 

The NONDESTRUCTIVE READ NO WAIT packet is used to look 
ahead one character into the driver’s cached input stream. If the driver 
has input data waiting to be read, the first character is returned directly 
into the packet. This character remains in the input queue for later service 
by a READ request packet. If the input queues are empty, the driver sets 
the BUSY flag in the status word. In no case does the driver block the 
request. 

3.3.2.3 Monitors The stream of data written from a device driver to a 
device controller, or from a device controller to the device driver, may be 
intercepted by user processes and examined or translated. Support for 
this translation mechanism (monitoring) may be provided by the char¬ 
acter device. 

Device monitor support differs from file I/O support in that monitors 
are supported almost entirely by the IOCtl interface between application 
software and the device driver, and require little file manager action. 
System support is provided with a special monitor dispatch process. 

At the application level, the DosMonOpen API is used to open a 
connection between a device and the process. The driver receives an 
OPEN strategy packet with the MON bit of the status bit set. When the 
DosMonClose API is issued, a CLOSE packet will be issued to the driver, 
also with the MON status bit set. This is the extent to which the file 
manager offers integral monitor support. The balance of application 
monitor support is provided by means of reserved IOCtl calls. 
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The device driver maintains a list of monitor chains, each of which 
contains a list of application-level monitor threads that perform the 
monitoring function. When the device driver receives the Monitor OPEN 
packet, it may create a new monitor chain with the DevHlp routine, 
MonitorCreate. When creating a new chain, the driver specifies a notifica¬ 
tion routine and a final buffer. 

The IOCtl packet Register is issued in response to the API call, Dos- 
MonReg. This packet contains the virtual address of the input buffer and 
output buffer associated with the monitor process. The device driver 
decides which monitor chain will contain the monitor process and issues 
the DevHlp request Register to register the monitor thread to the monitor 
dispatcher. The monitor packet places the monitor thread on the selected 
monitor chain and associates it with the input and output buffers of the 
monitor thread. 

The monitor chain is used by the driver in two basic ways—to intercept 
input data from the device, and to intercept output data to the device. 

Data is typically received from the device in an interrupt service 
routine. The interrupt service routine receives one or more input charac¬ 
ters and formats a monitor packet to contain those characters. The 
monitor packet format is specified by the monitor process, but the actual 
packaging of the characters is driver-defined. The driver and monitor 
processes must adhere to the same character packet format. 

The interrupt service routine then dispatches the character packet to 
a monitor chain using the DevHlp call, MonWrite. The monitor dispatcher 
writes the packet to the first input buffer in the chain, and starts the first 
monitor process. The interrupt service routine then terminates. If the 
monitor chain is full when the interrupt routine issues the MonWrite, an 
error code is returned. The interrupt routine must then discard the 
character (or perform other error recovery). 

When the first monitor process has examined or altered the contents 
of the packet in the input buffer, it places the packet in its output buffer. 
The monitor dispatcher then copies that packet to the input buffer of the 
next monitor process in the chain, and starts that process. 

When a packetized character has been placed in the output buffer of 
the last monitor process in the chain, the dispatcher places the character 
packet in the final buffer, and calls the notification routine. It should be 
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noted that the notification routine may be called in the context of the 
monitor dispatcher, or (if the monitor chain was empty) in the context of 
the routine that issued the MonWrite. This context typically will be 
interrupt context. The notification routine should be written to support 
real and protect interrupt context, and protect ring 0 context. 

The notification routine gets the character packet waiting in the final 
buffer, and extracts the characters. It places these characters in the device 
driver input character queue, where it is now available to be read by an 
application process. 

Data written to the device driver may also be monitored. This data is 
received from a WRITE strategy packet. The strategy routine takes 
characters from the physical buffer specified by the WRITE packet and 
packages the characters in a monitor character packet whose format is 
specified by the device driver. The strategy routine dispatches the char¬ 
acter packet to the selected monitor chain using the DevHlp routine, 
MonWrite. If the monitor chain is full, MonWrite blocks until it can write 
the character. 

The monitor dispatcher writes the packet to the input buffer of the first 
monitor process on the chain, and starts that process. The monitor thread 
writes the character packet to its output buffer. The monitor thread copies 
this packet to the input buffer of the next monitor thread, and starts this 
thread in turn. 

When the last thread in the chain writes a character packet to its output 
buffer, the monitor dispatcher copies the packet to the final buffer and 
calls the notification routine in its ring 0 context. If the monitor chain was 
empty when the strategy routine wrote the character to the monitor 
dispatcher, the notification routine will be called in strategy context. The 
notification may then be called in real or protect context, but not in 
interrupt context for this model. 

The notification routine will extract the character from the final buffer 
and write the character to the device controller to start I/O, or will buffer 
the character for use at interrupt time if the device is already busy. 

When a process issues a DosMonOpen API call or, if the process 
terminates after having issued a DosMonOpen API call and without 
issuing the corresponding DosMonClose API call, the driver receives a 
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CLOSE strategy packet with the MON bit set. The device driver is 
expected to issue the DevHlp DeRegister call to each monitor cha in to 
remove all monitor threads associated with the closing process from those 
chains. No facility for the deregistration of individual monitors exists. 

3.3.2.4 Character Queues Character flow is often buffered by the 
device driver for performance reasons. Character queue management 
routines are provided for management of character queues regardless of 
context; interrupt or strategy, real or protect. 

Character queue functions include the device helper functions Queue- 
Init to initialize the queue, Queue Write to write a character to the queue, 
and QueueRead to read a character from the queue. 

Characters are held in character queues or are implicitly buffered by 
the monitor chain. The file manager or application may require the driver 
to purge these queues in order to synchronize program action with device 
I/O. The file manager will issue the strategy packet FLUSH INPUT 
QUEUE or FLUSH OUTPUT QUEUE to cause the driver to purge the 
appropriate queue, and an application can issue IOCtl call Flush Input 
Buffer or Flush Output Buffer. 

When the driver receives a flush request, it clears the appropriate 
character queues with the DevHlp call, QueueFlush. The driver then 
issues the DevHlp call, MonFlush, to flush the appropriate monitor chain. 

3.3.2.5 Device Status Character device status is determined with 
strategy packets INPUT STATUS and OUTPUT STATUS. The driver is 
expected, upon receipt of an INPUT STATUS packet, to set the BUSY bit 
in the device header status word if no characters are currently buffered 
in the device driver input queue. The device driver clears the BUSY bit 
if at least one character is available for immediate read. This call is used 
to determine if a READ request of one character can be expected to return 
without blocking. 

The OUTPUT STATUS packet determines if the device is available for 
immediate output. The driver sets the BUSY bit if a request for output is 
pending and any WRITE request would have to wait until the first request 
reached completion. The driver will clear the BUSY flag if the device is 
available for immediate use. 
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3.3.3 IOCtl Interface 

The IOCtl interface is used to issue I/O requests from a process to a device 
driver without intervention. onsupportTrom the file-manager. These IOCtl 
c alls result in the issuance of an IOCtl packet to the device driver strategy 
routine. The device driver must have set the GIO bit in its header word 
hefdre initializ e time in order to indicate to the operating system that it 
supports the IOCtl interface, and should be configured-as-a character 
device driver. _ 

Every IOCtl call is associated with a category code’and a function code. 
The category code specifies the general type of device controlled by that 
IOCtl and the function code dictates specific action to be taken by the 
device driver. Category codes 1-127 are reserved for system use. Applica¬ 
tion programs may use codes 128-255. 

An IOCtl strategy packet also contains a virtual parameter buffer and 
a data buffer address. These addresses are not locked by the file system 
and must be locked and converted to physical addresses if they are to be 
used by the interrupt service routine. The length and format of the 
parameter buffer and data buffer are defined by the application and 
device driver. 

3.3.4 Device Helper Functions 

Most DevHlp functions may be used at strategy time. These routines may 
be divided into functional categories: process management, memory 
management, interrupt management, semaphore management, timer 
management, character monitor management, request queue and char¬ 
acter queue management, and system services. 

3.3.4.1 Process Management at Strategy Time Three major process 
management functions are provided by the device helper routine—coor¬ 
dination of the strategy and interrupt (or another strategy) routines, 
yielding to high priority threads, and running a real mode strategy 
routine in protect mode. 

Coordination of the strategy thread with an interrupt thread is done 
by performing a Block call to the DevHlp interface. The strategy thread 
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passes the physical address of the request packet to the call, and the 
interrupt routine can later unblock the strategy thread with a Run call. 

Coordination between strategy threads is done by one routine c alling 
Block to suspend itself and the other unblocking the first with Run. Many 
threads may wait on a single Run. The blocked thread will awaken with 
interrupts enabled, even if they were disabled at the time of the block. 

If a strategy routine is expected to perform lengthy computations, it 
should periodically (every 3 milliseconds) check the Yield or TCYield flags 
to determine if a higher priority thread is waiting for service. The strategy 
routine will not be preempted by any other thread (except interrupts) once 
it starts, and so even higher priority threads must wait until the strategy 
routine suspends. The strategy routine can ask that higher priority 
threads be given a time-slice with the Yield and TCYield DevHlp calls. 

Finally, a strategy routine that starts in real mode can switch context 
to protect mode. This is done with the RealToProt call. The strategy 
routine must return to real mode (with ProtToReal) before it blocks or 
suspends for any reason, or before returning to the kernel. Some DevHlp 
routines carry the implicit possibility of a block, and must be used with 
caution in this context. The time penalty for a context switch from protect 
$0 real mode is. 3 milliseconds on the 80286. 

3.3.4.2 Memory Management at Strategy Time The strategy time 
memory management is influenced by the real/protect mode in which the 
strategy routine is invoked. If a strategy routine is known to be invoked 
only from real or only from protect mode, certain simplifying assumptions 
may be made. Even bi-modal strategy routines may be able to manag e 
memory by determining their mode from the machine status word 
(MSW). Some occasions, however, mandate use of bi-modal memory 
management. 

Protect Mode: The strategy routine runs in the context of the kernel 
and of the underlying process, allowing access to memory which is 
mapped by the global descriptor table (GDT) or the local descriptor table 
(LDT). If the strategy routine wishes to map memory in another local 
address space, it must obtain the physical address of that memory- 
Physical addresses can be mapped for use by the strategy routine. 
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A more characteristic memory management function at strategy time 
is the locking of virtual addresses, and possibly mapping those addresses 
to the GDT. These addresses (or GDT selectors) may be used by the 
interrupt service routine to access the memory. 

Memory that is to be made accessible by the interrupt service routine 
must be locked into memory with the DevHlp call, Lock. The DevHlp call, 
VirtToPhys, returns a physical address that is valid until that memory is 
released with the Unlock DevHlp call. Note that reference to a virtual 
address in the strategy routine may result in the strategy routine blocking 
if the virtual address is not present in memory. 

Memory may be allocated to the device driver with the DevHlp call 
AllocPhys. This memory is accessible until released by PreePhys. 

Physical memory addresses must be mapped to either the global or local 
address space before use. A block of physical memory (1-64K bytes) is 
mapped to a GDT selector with the DevHlp call, PhysToGDTSelector. The 
GDT selector which is mapped in this way should be one that was 
allocated at initialize time by AllocGDTSelector. This mapping can now 
be used by any protect mode process or interrupt service routine function¬ 
ing in protect mode. 

Physical memory addresses can be mapped to the virtual address space 
of the underlying process with PhysToUVirt. These addresses may be 
used by the strategy routine, or the underlying process. Addresses 
mapped through the LDT cannot be expected to be valid at interrupt time. 

Virtual addresses passed to the device driver should be checked for 
validity with the DevHlp call, VerifyAccess. VerifyAccess determines if 
the calling process has access rights to the virtual address. VerifyAccess 
should be called before performing a lock of the virtual address. 

Whenever the strategy routine blocks, the underlying process may 
deallocate memory or it may lose access rights to the virtual address 
passed earlier to the device driver. If the memory is not locked, it should 
be checked for validity before use after each strategy routine suspension. 

Real Mode: The strategy routine can only access memory below 1M. The 
strategy routine can map physical addresses to the GDT, but cannot use 
these addresses itself. Since there is no underlying LDT, the local virtual 
address translations cannot be performed. 
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The strategy routine can allocate physical memory with AllocPhys, and 
free it with FreePhys. This memory can be allocated in the 1M region 
accessible to the real mode process, or above 1M where it is accessible by 
protect mode processes. 

Bi-modal Operations: Allocation of memory can be performed in either 
real or protect mode. However, mapping of memory in a mode-inde¬ 
pendent way can take place only using the DevHlp call, PhysToVirt. 

PhysToVirt allows the mapping of only two simultaneous addresses. 
Each address may reside anywhere in memory. In protect mode, two 
global selectors are reserved by the system for the performance of this 
mapping, one for DS and one for ES. PhysToVirt maps the physical 
memory to the appropriate selector and places the selector value in the 
selected segment register (DS or ES). 

In real mode, the situation may be quite different, and depends on the 
underlying machine architecture. On 80386 machines, mapping of an 
address above 1M will cause a mode switch to protect mode. If the second 
address of a pair caused the mode switch (i.e., the first address was below 
1M), the first address must be mapped again in the protect mode context 
before use. If either segment register DS or ES points to the driver main 
data segment, its contents will be converted to point to the main data 
segment in the new context. All other real mode addresses will be invalid. 

On 80286 machines, addresses above 1M are mapped using the undocu¬ 
mented 80286 instruction LOADALL. The contents of the segment 
register (DS or ES) cannot be interpreted in any normal context (i.e., they 
are not mapped to a GDT or LDT). The contents of these registers are 
protected by PhysToVirt, which disables interrupts in the 80286 case. 

Real/protect mode-independent address translation is supported by 
PhysToVirt as long as only one pair of addresses is used at any one time. 
After the address pair is mapped and used, UnPhysToVirt should be used 
to terminate the mapping function before mapping any other addresses. 
In addition, no mapped addresses can be stored for later use, and no stored 
virtual addresses in either global or local address space can be used while 
the mappings are taking place. However, addresses that reference the 
main data segment will remain valid as long as the main data segment 
address is contained in the segment register DS or ES at the time of the 
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DevHlp call, PhysToVirt. Interrupts must not be enabled between the use 
of PhysToVirt and UnPhysToVirt. The strategy must not block between 
the use of PhysToVirt and UnPhysToVirt. Device helper routines may not 
be called between the use of PhysToVirt and UnPhysToVirt. 

3.3.4.3 Interrupt Management at Strategy Time An interrupt level 
may be intercepted or released at strategy time. If a previously unused, 
or shared, interrupt is to be intercepted, the driver issues the SetIRQ 
DevHlp call. To release a hardware interrupt, the DevHlp routine, 
UnSetIRQ, is called. 

3.3.4.4 Semaphore Management at Strategy Time Serialization of 
strategy threads or application threads is accomplished with semaphores. 
System and RAM semaphores may be used to coordinate threads, but only 
RAM semaphores can be allocated by a device driver. System semaphores 
must be passed by an application to the device driver before they can be 
used. FSRAM semaphores are not supported. 

System semaphore handles returned to the application must be con¬ 
verted to system-wide handles before they can be used by the driver, and 
this handle must be later released (both functions are accomplished with 
DevHlp call, SemHandle). The virtual address of a RAM semaphore is to 
be used as a semaphore handle, but is valid only in the context of the 
proper address space. As an example, RAM semaphores allocated by a 
process in its local address space cannot be cleared by an interrupt 
routine. RAM semaphores in global memory must be locked before use at 
interrupt time. 

A semaphore is requested by the strategy routine with DevHlp call, 
SemRequest. If the semaphore is available, the call returns immediately. 
If not, the thread suspends until the semaphore becomes available. If 
several threads are blocked waiting for the same semaphore, the highest 
priority thread will next claim the semaphore. The semaphore is released 
with SemClear. SemClear may be issued at strategy time, or interrupt 
time. 


3.3.4.5 Timer Management at Strategy Time The strategy routine 
may have need for time management for device time-out, polling interval, 
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or other time-related functions. OS/2 provides a timer routine callable at 
intervals of one or more clock ticks (31.25 milliseconds on the AT or PS/2). 
A system-defined maximum of 32 timer entry points is available. 

The strategy routine may create a timer routine that is callable every 
clock tick (SetTimer), or every fixed number of clock ticks (TickCount). 
The DevHlp routine, TickCount may also be used to change the interval 
at which a timer handler is called in order to specify a fixed number of 
clock ticks. The handler is removed with DevHlp routine, Reset Tim er. The 
timer routine will always be called in protect mode. 

The DS register must be set to the selector address of the main data 
segment before making this call. This means the no PhysToVirt conver¬ 
sion should be pending and if a RealToProt call was issued, the context 
must be returned to real mode. 

3.3.4.6 Monitor Management at Strategy Time The strategy routine 
will manage monitors in response to the Monitor OPEN and Monitor 
CLOSE packets; the IOCtl packet, Register a Monitor, and in response to 
the READ and WRITE packets. 

The Monitor OPEN packet is issued in response to an API DosMonOpen 
command. The driver may create a monitor chain in response to this 
packet (DevHlp call, MonitorCreate). The driver specified the address of 
a final buffer and a notification routine, which will be used to communi¬ 
cate a character returned from the monitor chain to the device driver. 

The application may issue the DosMonReg API call to register a 
monitor thread to the driver. The driver will receive the IOCtl packet, 
Register a Monitor. The driver determines on which monitor </hain to 
place the monitor thread and issues the DevHlp call, Register. 

Upon receipt of a WRITE packet, the driver may issue a MonWrite 
DevHlp call to write the character to the monitor chain. When processed 
through all monitors on the chain, the character is written to the final 
buffer and the notification routine is started. The notification routine will 
write the character to the device. 

On receipt of an input interrupt, the interrupt service routine may read 
the character from the device and write the character to the monitor nhain 
using MonWrite. When processed through all monitors in the chain, the 
character is written to the final buffer and the notification routine is 
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started. The notification routine will place the character in the buffer 
selected by the READ packet. 

On receipt of a Monitor CLOSE packet, the driver will remove all 
monitor threads on any of its chains that are associated with the process 
which issued the close. The DevHlp call, DeRegister, is used to purge a 
fViflin of all monitors associated with a single process (no facility exists 
for removing a single monitor thread from a chain). The driver may choose 
to delete the chain with MonitorCreate. 

The driver may be called upon to flush the characters in a monitor chain 
(in response to strategy packets INPUT FLUSH or OUTPUT FLUSH, or 
IOCtl packets Flush Input Buffer or Flush Output Buffer). The driver will 
issue DevHlp call, MonFlush, to flush the monitor chain. 

3.3.4.7 Queue Management at Strategy Time Two types of queues 
are supported by DevHlp calls: strategy packet queues and character 
queues. 

Strategy packets are used to represent an I/O request. These packets 
must often be serviced in sequence, as typical devices can handle only one 
request at a time. The driver will place packets on a queue to represent 
the sequence of pending operations. 

Certain operations require several distinct processes. For example, 
WRITE/VERIFY requires the driver to perform a write operation, a read 
operation, and a buffer compare. The driver might elect to use multiple 
strategy packets to represent this flow of control. If so, the driver allocates 
the packets, queues them, and releases them when done. 

The strategy packet queue head is a DWORD area located in the main 
data segment. The driver initializes this value to 0. 

A strategy packet is placed on the queue in FIFO order with DevHlp 
call, PushReqPacket, or in ascending sector number order with SortReq- 
Packet. The algorithm of sorting entries in sector number order is a fairly 
naive optimization algorithm that does not allow for multiple head 
devices nor does it compensate for current I/O track number. 

The strategy packet at the head of the queue is selected (and removed) 
with PullReqPacket, and a particular packet is removed with Pull- 
particular (say in case of time-out). 
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These routines do not inhibit interrupts. The driver writer is required 
to clear the interrupt flag before calling these routines if there is any 
possibility the calling context may be interrupted by an interrupt service 
routine which might examine or alter the same strategy packet queue. 
This protection is needed in all strategy routines that examine the queue 
and even in an interrupt routine that allows nesting. If use of the queue 
management routines is restricted to strategy context (unlikely), this 
protection is not needed. 

Additional strategy packets may be allocated for temporary use by the 
driver with AllocReqPacket. These packets have tiled addresses, which 
makes them suitable for use on a queue both in real or protect mode. Tiled 
addresses, however, are a scarce commodity, so these packets should be 
released as quickly as possible (FreeReqPacket). 

Character queue handling services are also provided for driver use. The 
driver creates a circular queue structure composed of the queue size word, 
an index word, and a buffer of bytes into which the characters will be 
placed. The queue is initialized with Queuelnit. A character is written to 
the queue with Queue Write, and read from the queue with QueueRead. 
The queue is flushed with QueueFlush. 

The character queue handling routines provide interrupt protection 
and return the interrupt bit of the PSW to its value when the call is made. 
Thus, queue routines may be called at strategy or at interrupt time 
without fear of interference or interruption. 

3.3.4.8 Communication Between Drivers The strategy routine may 
set up a link to another device driver. This link is established with a driver 
that supports inter-device driver communication (IDC) with the 
AttachDD helper service. AttachDD returns the CS:offset of the IDC entry 
point and the DS of the driver. Both real and protect mode CS and DS are 
returned. 

The strategy routine may now call the cooperating driver. The strategy 
routine must determine (from the MSW) if it is operating in real or protect 
mode, and it must set up DS and CS to the target driver’s correct values 
in making the call. The interpretation of registers other than CS and DS 
is determined by cooperation of the device drivers. 
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Any device driver that accepts IDC link requests mustbe-a-character 
device driver, and must have the IDC bit set in the device header word at 
initialize time. 

3.3.4.9 System Services at Strategy Time The system will use 
GetDOSVar to provide access to system-defined variables at strategy 
time. The variables available at strategy time include the global and local 
INFO segments, the reboot-vector; and the YieldFlag and TCYieldFlag. 

The global INFO segment points to a segment containing mformation 
of global applicability that includes time, date, clock tick granularity, and 
other system constants. The format of the local and global INFO segments 
is included in the appendices. 

The local INFO segment points to a segment associated with the 
underlying process that caused the strategy routine to be called. Infor¬ 
mation included in this segment includes local process and thread ID, 
thread priority, and other process information. 

If the strategy routine will be performing extensive computations, the 
TCYieldFlag should be sampled every 3 milliseconds to determine if a 
time-critical thread has been scheduled for execution. If one has, the 
strategy routine should call DevHlp routine, TCYield, to yield scheduling 
control and allow the waiting time-critical threads to run. The strategy 
routine otherwise will not yield control until it executes a Block or 
suspends. 

The strategy routine can sample the YieldFlag—instead of the TCYield¬ 
Flag—to determine if any thread of higher priority than the current 
thread is waiting to run, not just time-critical threads. 

3.4 Interrupt Time 

When the processor acknowledges a PIC interrupt request, the interrupt 
manager is called. The interrupt manager saves all registers, determines 
the current processor real/protect context, sets the correct DS and CS 
values for that context, and issues a FAR CALL to the device driver 
interrupt service routine. The interrupt routine performs any processing 
as quickly as possible and returns with carry bit=0 (processor instruction 
CLC) to indicate the routine has serviced the interrupt. The interrupt 
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service routine should set carry bit=l (processor instruction STC) if it does 
not service the interrupt, allowing the interrupt request to be sent to the 
next routine. 

The interrupt service routine is started with the processor interrupt 
flag cleared (interrupts disabled), and the hardware interrupt level dis¬ 
abled at the PIC. The interrupt routine is, at this point, uninterruptible. 
Note that interrupt routines that share a single IRQ are entered with 
interrupts enabled to reduce interrupt latency. 

The interrupt routine should run in disabled context for an extremely 
short time (400 microseconds), as all other system processing is 
suspended. The service routine should enable interrupts at the processor 
(STI) within that period. 

The interrupt routine is now protected against interrupt by any 
1 strategy context and by its device controller (by the PIC). If the interrupt 
routine is to perform any significant processing, it may enable interrupts 
at the PIC (DevHlp call, EOI) so that additional interrupts are not lost 
by device overrun. This will cause nesting of the interrupt service routine 
by additional interrupt requests by the same device controller. The 
interrupt service routine must protect itself against these interrupts by 
serializing the requests, and must protect the system against stack 
overrun. , 

The interrupt routine cannot block or suspend, and is restricted to use 
of DevHlp routines that cannot suspend. The available routines can be 
divided into functional categories: process management, memory 
management, interrupt management, semaphore management, timer 
management, character monitor management, request queue and char¬ 
acter queue management, and system services. 

3.4.1 Process Management at Interrupt Time 

The interrupt service routine is capable of unblocking a strategy thread 
with the Run DevHlp call. If the strategy routine returned to the kernel 
before setting the DONE bit of the packet header word, the kernel had 
suspended that thread. The interrupt routine will set completion status 
in the strategy packet, then unblock the strategy thread with the DevHlp 
call, DevDone. 
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If the interrupt routine was called in real mode, it may convert to a 
protect mode context with the DevHlp call, RealToProt. The routine must 
res um e real mode context (ProtToReal) before returning. 

3.4.2 Memory Management at Interrupt Time 

The interrupt service routine is called asynchronously to any user process, 
so no virtual address mapping to application processes is supported at 
interrupt time. Allocation or deallocation of physical memory is not 
supported. Allocation of GDT selectors is not supported. 

The interrupt routine can map physical memory to a GDT selector, and 
may use that selector to address memory if it is running in protect mode. 
The interrupt routine should not use GDT selectors which represent 
unlocked memory. It can map memory independent of real/protect mode 
context with the DevHlp call, PhysToVirt. 

PhysToVirt allows the mapping of only two simultaneous addresses. 
Each address may reside anywhere in memory. In protect mode, two 
global selectors are reserved by the system for the performance of this 
mapp ing , one for DS and one for ES. PhysToVirt maps the physical 
memory to the appropriate selector and places the selector value in the 
selected segment register (DS or ES). 

In real mode, the situation may be quite different, and depends on the 
underlying machine architecture. On 80386 machines, mapping of an 
address above 1M will cause a mode switch to protect mode. If the second 
address of a pair caused the mode switch (i.e., the first address was below 
1M), the first address must be mapped again in the protect mode context 
before use. If either segment register DS or ES points to the driver main 
data segment, its contents will be a converted value usable in the new 
context. All other real mode addresses will be invalid. 

On 80286 machines, addresses above 1M are mapped using the undocu¬ 
mented 80286 instruction LOADALL. The contents of the segment 
register (DS or ES) cannot be interpreted in any normal context (i.e., they 
are not mapped to a GDT or LDT). Interrupts are cleared by PhysToVirt 
in real mode to protect the unusual context in which the processor will 
run. The interrupt flag must not be altered before UnPhysToVirt is issued. 
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Real/protect mode-independent address translation is supported by 
PhysToVirt as long as only one pair of addresses is used at any one time. 
After the address pair is mapped and used, UnPhysToVirt should be used 
to terminate the mapping function before mapping any other addresses. 
In addition, no mapped addresses can be stored for later use and no stored 
virtual addresses in either global or local address space can be used while 
the mappings are taking place. However, addresses that reference the 
main data segment will remain valid as long as the main data segment 
address is contained in the segment register DS or ES at the time of the 
DevHlp call, PhysToVirt. The interrupt flag must not be altered between 
the PhysToVirt call and the UnPhysToVirt call. No helper services may 
be used between the PhysToVirt call and the UnPhysToVirt call. 

UnPhysToVirt must be called to terminate the mapping function before 
the interrupt routine returns. The interrupt service routine can use the 
DevHlp call, Unlock, to release locked memory (but cannot lock it). 

3.4.3 Interrupt Management at Interrupt Time 

The hardware interrupt can be enabled at the PIC with the DevHlp call, 
EOI. If this call is not issued, this interrupt level will remain permanently 
disabled. 

If it is the intent of the interrupt routine to disable a device permanent¬ 
ly, it should release the interface to the IRQ level with DevHlp call 
UnSetIRQ. 

3.4.4 Semaphore Management at Interrupt Time 

The interrupt routine can clear a semaphore, unblocking all waiting 
threads with DevHlp call, SemClear. The highest-priority thread will 
obtain the semaphore, and all other threads will suspend. 

3.4.5 Timer Management at Interrupt Time 

The interrupt service routine is not allowed to add timer entry points. The 
routine can change the number of ticks between invocations of the timer 
routine with TickCount, and can release the timer with Reset Tim er. 
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3.4.6 Monitor Management at Interrupt Time 

The interrupt routine can write a character packet to the monitor chain 
in non-wait mode (MonWrite). If the input buffer is full, the MonWrite 
request will return immediately with error. 

3.4.7 Queue Management at Interrupt Time 

Strategy packets cannot be enqueued at interrupt time. The interrupt 
routine is limited to removing the first packet from the queue (PullReq- 
Packet), or removing a packet whose address is known (PullParticular). 

A strategy packet queue that is accessed at both strategy and interrupt 
time must be protected by the strategy routine from simultaneous access. 
At interrupt time, if the interrupt service routine has enabled interrupts 
and issued EOI, allowing nested interrupts, the queue must be protected 
against simultaneous access by two instances of the same interrupt 
service routine. Each routine would clear the interrupt flag before access¬ 
ing the queue, and restore it afterwards. 

Full character queue support is provided to the interrupt service 
routine. Character queues may be initialized with Queuelnit. Acharacter 
is written to the queue with QueueWrite, read from the queue with 
QueueRead, and emptied with QueueFlush. 

3.4.8 IDC Interface at Interrupt Time 

The IDC interface function, AttachDD, cannot be called from interrupt 
context. The interrupt routine can call another driver whose interface has 
already been attached. The interrupt routine must select the target CS 
and DS values based upon the current real/protect mode of the processor, 
and perform a FAR CALL to the driver entry point. 

3.4.9 System Services at Interrupt Time 

The system provides access to system-defined variables at interrupt time 
with GetDOSVar. The variables available at interrupt time include the 
global INFO segment and the reboot vector. The global INFO segment 
contains information that is system-wide—such as time, date, and clock 
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tick granularity. The global INFO segment format is defined in the 
appendices. 

3.5 Notification Time 

When a character device driver creates a monitor chain, it passes the 
addresses of a final buffer and a notification routine to the monitor 
dispatcher. 

When the device driver issues a MonWrite DevHlp call to write a 
character packet to the monitor chain, the monitor dispatcher determines 
if the monitor chain is empty or not. If the chain is empty, the dispatcher 
places the character packet in the final buffer and calls the notification 
routine in the device driver context in which the MonWrite was issued. 
The MonWrite DevHlp call can be issued in real or protect mode, and in 
interrupt or strategy context. 

If the monitor chain is not empty, the monitor dispatcher writes the 
character packet to the input buffer of the first monitor thread on the 
chain. This thread processes the packet and writes it to its output buffer. 
The monitor dispatcher copies the character from the first monitor 
thread’s output buffer to the input buffer of the next monitor thread on 
the chain. 

When a character packet is written to the last output buffer in the 
monitor chain, the monitor dispatcher copies the character packet to the 
final buffer, and calls the notification routine in its own protect mode 
context. 

The dispatch routine may therefore be called in interrupt, strategy, or 
other protect mode context; and in real or protect mode. The driver writer 
should adhere to interrupt time restrictions in order to guarantee a 
well-behaved notification routine. 

3.6 Clock Tick 

A clock tick is received every 31.25 milliseconds (or a driver-defined 
multiple of 31.25 milliseconds) at the timer entry point. Interrupts are 
enabled, and processing should be extremely rapid, as clock overhead 
degrades overall system performance. 
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The tim er service routine is called in protect mode, and contents of all 
registers must be preserved. Otherwise, the timer service routine adheres 
to all restrictions of the interrupt service routine, and may use all support 
fa cilit ies available to the interrupt service routine . 

3.7 Driver Communication Time 

Device driver communication is essentially a cooperative procedure be¬ 
tween two drivers (see Figure 3-15). Any driver that is to receive com¬ 
munications must be a character device driver and must have the IDC bit 
set in its device driver header word at initialize time and must also specify 
its main code segment IDC entry point in the header word. 

Figure 3-15: IDC Registers are set by Calling Driver_ 
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The transmitter driver makes the DevHlp call, AttachDD, at initialize 
or strategy time. This call returns the main code and main data segment 
register values for both real and protect mode, and the offset of the 
receiver IDC entry point in the receiver’s main code segment. 

The transmitter driver may call the receiver in real or protect mode, 
and in strategy or interrupt context. The transmitter must determine the 
current real/protect mode context (by examining the MSW), and set the 
CS and DS values for the receiver accordingly. The transmitter then calls 
the receiver. 

The receiver gains control at its IDC entry point. Whether this entry 
point is called in strategy or interrupt context is a matter of convention 
determined between the two drivers. 

Argument passage, saving of registers, and use of registers is also 
governed by driver convention. The DevHlp calls available to the receiver 
are determined by the strategy/interrupt context of the caller. The 
receiver surrenders control with a Far return (RETF). 



CHAPTER 4 


STKATEGY PACKET DETAILS 


The strategy packet is the exclusive means by which requests for data or 
information are forwarded from OS/2 API calls through the file manager 
and the kernel to the device driver. The device driver is called at the 
strategy entry point with ES:BX pointing to the strategy packet. Control 
is passed to the strategy entry point in the real/protect mode of the process 
that issued the API cadi originating the request (or in protect mode for 
requests originating from the file manager). As strategy “packets have. 
..til ed a ddresses, they may be accessed in either mode. 

If control is passed in protect mode, ring 0 protection level is used for 
all packets except the INIT packet. This allows access to the global 
descriptors, an d therefore to all system data structures. The INIT packet 
occurs at ring 3 protection level, but is granted access to the global 
descriptor table due to the unique context of the initialization process. 

All strategy packets share the same header format, that communicates 
the strategy packet command code to the strategy routine and returns 
error status to the kernel, which forwards completion status to the file 
manager or the application. Strategy packets may be divided into four 
areas of functionality: initialize, block device, character device, and IOCtl. 

The two initialize packets are INIT and DEINSTALL. INIT is issued 
once for each device driver header. Character- device-loadmodules may 
haye-several-device driver headers .(block drivers have only one header). 
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If, once a character driver has been initialized by the system, a subsequent 
driver with the same name is found, a DEINSTALL packet will be sent 
to the first driver. If the first driver refuses the DEINSTALL request, the 
second driver will not be initialized. If the first driver accepts the 
DEINSTALL request, an INIT packet will be sent to the second driver. 

Block device drivers may configure themselves (in the device driver 
header attribute word) as removable media. Block device drivers of all 
types are expected to service the MEDIA CHECK, BUILD BPB, and 
RESET MEDIA strategy packets once, in order to establish the device 
parameters to the file system. Removable media device drivers can expect 
to receive these packets regularly, as the file system attempts to ascertain 
the integrity of the media before performing directory manipulation. 
Removable media device drivers also support the REMOVABLE MEDIA 
packet. 

Block device drivers service the Device OPEN, Device CLOSE, READ, 
WRITE, and WRITE/VERIFY strategy packets. Partitionable devices 
also service the strategy packets PARTITIONABLE FIXED DISKS and 
GET FIXED DISK/LOGICAL UNIT MAP. Block devices are expected to 
service certain standard GENERIC IOCtl packets, and may service 
additional packets defined by the driver writer. The standard block device 
GENERIC IOCtl strategy packets often reproduce the functionality of file 
manager-generated strategy packets. The interrelationship between the 
functions of supported GENERIC IOCtl packets and strategy packets is 
outlined in Table 4-1. 


Table 4-1; IOCtl Packets vs. Strategy Packets 


GENERIC IOCtl PACKET 

Get Device Parameters/Set Device 
Parameters 

Redetermine Media 

Block Removable 

Get Logical Unit Map 

Set Logical Unit Map 


EQUIVALENT STRATEGY PACKET 
BUILD BPB (Not Fully Equivalent) 

RESET MEDIA 
REMOVABLE MEDIA 
GET LOGICAL DRIVE MAP 
SET LOGICAL DRIVE MAP 
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Additional block device GENERIC IOCtl Packets: 

• Lock Logical Unit 

• Unlock Logical Unit 

• Read Track 

• Write Track 

• Verify Track 

• Format and Verify Track 

• Lock Physical Drive 

• Unlock Physical Drive 

• Get Physical Device Parameters 

• Physical Read Track 

• Physical Write Track 

• Physical Verify Track 

Character device drivers support the Device OPEN, Monitor OPEN, 
Device CLOSE, Monitor CLOSE, READ, NONDESTRUCTIVE READ 
NO WAIT, WRITE, INPUT STATUS, OUTPUT STATUS, INPUT 
FLUSH, and OUTPUT FLUSH. Character device drivers often support 
system-defined GENERIC IOCtl packets, and character drivers often 
define custom GENERIC IOCtl packets as well. These are the. standard 
character driver GENERIC IOCtls: 

• Query Monitor Support 

• Register Monitor 

• Flush Input Buffer 

• Flush Output Buffer 

Custom, IOCtl-only drivers just need to support IOCtl packets, whose 
format and function are specified by the driver writer. These drivers are 
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configured as character device drivers in order to circumvent the file 
manager/block device interface. 

4.1 Strategy Packet Header 

The strategy packet header is 13 bytes in length. At strategy entry, the 
packet command code is contained in the packet. For block devices, the 
logical unit number to be serviced is also included. 

When the driver has completed service of the request packet, it sets the 
status word in the request packet header. The status word communicates 
final request status to the kernel, which returns error status to the calling 
program, file manager, or OS/2 application program. 


4.1.1 Strategy Header Details 

The strategy packet header is defined as follows: 


LENGTH BYTE 

UNIT BYTE 

COMMAND BYTE 

STATUS WORD 

RESERVED DWORD 

LINKAGE DWORD 


LENGTH. Contains the total packet length, the 13-byte header and the 
command-specific portion. Each packet’s format is clearly defined and 
known to the driver; so the LENGTH field is not normally used by the 
driver. The strategy routine determines the packet type with the COM¬ 
MAND field. 

UNIT. For block drivers only, the unit for which the packet is intended is 
specified in this field. Each block device driver may support multiple 
logical units. ' 

COMMAND. The strategy command code is contained in this field. The 
command code is the means by which the strategy routine determines 
which packet it is handling, as strategy entry is always made at the same 
point with the address of the strategy packet in ES:BX. 
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STATUS. This field is used to communicate completion and error status 
to OS/2. Four status bits are available to be set by the device driver: 
ERROR, DEVICEERROR, BUSY and DONE. A1 -byte error code is placed 
in the ERRORCODE field of STATUS. The format of the STATUS word 
is: 


ERROR Bit 15 

DEVICEERROR Bit 14 
RESERVED Bits 10-13 

BUSY Bit 9 

DONE Bit 8 

ERRORCODE Bits 0-7 

DONE. The DONE bit is set by the strategy routine when the request is 
complete, after which the strategy routine may return. If the strategy 
routine returns before setting this bit, the driver’s interrupt service 
routine must set this bit and issue the DevHlp call, DevDone. The other 
three status bits ERROR, DEVICEERROR, and BUSY are significant 
only after the bit DONE is set. 

ERROR. Status bit ERROR indicates that some error has taken place. 
The actual error code is placed in the ERRORCODE field of the status 
word. Error codes may be "user-defined," "driver-defined," or "system- 
defined." User-defined error codes are returned in response to user- 
defined IOCtl calls (category 128-255), and are returned as OS/2 error 
OFFOOh, ORed with ERRORCODE. Driver-defined error codes are 
specified by setting the DEVICEERROR bit and they are returned as 
OFEOOh, ORed with ERRORCODE. Table 4-2 lists system-defined errors, 
which are translated by the file manager into error codes received by the 
application. 


Table 4-2: System-defined Errors 


CODE 

0 

1 

2 

3 

4 

5 


ERROR 

Write Protection Violation 
Unknown Unit 
Device Not Ready 
Unknown Command 
CRC error 

Bad request packet length 
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Table 4-2: System-defined Errors 


CODE 

ERROR 

6 

Seek error 

7 

Unknown Media 

8 

Sector Not Found 

9 

Printer Out of Paper 

OAh 

write Fault 

OBh 

Read Fault 

OCh 

General Failure 

ODh 

Logical Change Disk 

lOh 

Uncertain Media 

llh 

Character I/O interrupted 

12h 

Monitors Not Supported 

13h 

Invalid Parameter 


BUSY. BUSY is set by the driver to return driver status in response to 
INPUT STATUS and OUTPUT STATUS, or in response to REMOVABLE 
MEDIA. 

STATUS. An extraordinary interpretation of this field exists on receipt 
of OPEN and CLOSE packets by character device drivers that support 
monitors. Bit 3 of the STATUS word contains the MON bit, which 
indicates whether the packet is an open/close request for the device or a 
monitor open/close request. 

LINKAGE. This double word is used by the strategy packet queue in g 
routines. The strategy packet is tiled and may be used without regard to 
real/protect context. This field may be used by driver-defined queu eing 
routines. 

4.2 Initialization 

Every device driver load module contains one or more device drivers, each 
defined by a device driver header in the main data segment (block device 
drivers have only one header). Each driver (as defined by a single header) 
is initialized at OS/2 startup time, as the load module is loaded per the 
"DEVICE=" statement in CONFIG.SYS. The loading of a character device 
may cause deinstallation of an earlier character device of the same name. 
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4.2.1 INIT (Command Oh) 

The INIT packet is received by the strategy-routine in ring 3 protect mode 
context for OS/2 level drivers and in real mode for DOS level drivers. The 
driver level is specified in the device driver header word. 

On input, the INIT packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

UNUSED 

ODh 

BYTE 

DEVHLP OFFSET 

OEh 

WORD 

SEGMENT 

lOh 

WORD 

CONFIG OFFSET 

12h 

WORD 

SEGMENT 

14h 

WORD 

STARTDRIVE 

16h 

BYTE 


LENGTH. LENGTH contains the INIT packet length, 17h. 

COMMAND. COMMAND is 0 for the INIT packet. 

UNIT, STATUS, RESERVED, LINKAGE, and UNUSED are not used 
on input. 

DEVHLP. DEVHLP contains the tiled FAR address of the device helper 
routine. This address should be stored for later use by the device driver. 

CONFIG. CONFIG contains a FAR pointer to the device driver 
parameter string as defined in the DEVTCE= command in CONFIG.SYS. 
The parameter string is composed of the device driver filename, followed 
by blank-separated arguments, and the string is null-terminated. 

STARTDRrVE. STARTDRIVE is applicable only to block devices and 
contains the number of the next logical unit the file manager expects to 
install. 

On output, the driver uses the following strategy packet format: 

LENGTH 0 BYTE 

UNUSED 1 BYTE 
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UNUSED 
STATUS 
RESERVED 
UNUSED 
UNITCOUNT 
CODELENGTH 
DATALENGTH 
BPBPTR OFFSET 
SEGMENT 
UNUSED 


2 

BYTE 

3 

WORD 

5 

DWORD 

9 

DWORD 

ODh 

BYTE 

OEh 

WORD 

lOh 

WORD 

12h 

WORD 

14h 

WORD 

16h 

BYTE 


LENGTH. The LENGTH field contains 17h on entry and is not altered 
by the device driver. 

STATUS. The STATUS word is set to lOOh to indicate successful instal¬ 
lation, or 810Ch (error OCh, General Failure) to indicate installation 
failure. 

UNITCOUNT. Character devices set UNITCOUNT to 0. Block devices 
set UNITCOUNT to the number of logical units supported by the device. 

CODELENGTH. CODELENGTH is used to set the length of the main 
code segment after initialize time. If the driver places the initialize code 
at the physical end of the main code segment, the driver may shorten the 
segment after initialize time. If the driver fails at installation, 
CODELENGTH should be set to 0. The actual code segment will not be 
resized until all device driver headers for the device driver have been 
initialized, at which time it will be reduced to the last non-zero value. If 
all headers return zero main code segment lengths, the main code seg¬ 
ment will be unloaded. 

DATALENGTH. DATALENGTH is set to the length of the data segment 
after initialize time. If the driver places initialization data at the end of 
the main data segment, the driver may shorten the data segment after 
initialize time. If the driver fails to install, it sets DATALENGTH to 0. 
The main data segment will not actually be resized until all device driver 
headers have been initialized for the driver, after which time the data 
segment will be reduced to the last non-zero size. If all headers return 
zero main data segment lengths, the main data segment will be unloaded. 
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BPBPTR. Character devices set BPBPTR to 0. Block devices set BPBPTR 
to a FAR pointer pointing to an array of near pointers to BIOS Parameter 
Blocks (BPBs), one for each logical unit supported by the driver. The BPB 
specifies the size and format of each of the logical units, and must be 
located in the main data segment of the device driver. The block driver 
initially should maintain the Uncertain Media state in order that the file 
manager request the volume ID be read by the driver, enabling volume 
ID checking. The block driver returns error code lOh (Uncertain Media) 
to all strategy packets after INIT, until the driver receives the RESET 
MEDIA strategy packet (COMMAND code llh). 

4.2.2 DEINSTALL (14h) 

After a character device driver is loaded, but before it is installed, the 
name in its header is checked against all installed devices. If a previously 
installed driver header had the same name, the DEINSTALL packet is 
sent to the installed driver. The installed driver decides whether to accept 
the DEINSTALL request, or to reject it. Two considerations are whether 
the driver expects deinstallation (possibly supporting vendor software 
upgrade) and whether the device controller is sufficiently well behaved 
to allow the deinstallation to take place. Should the driver select deinstal¬ 
lation, it should release all allocated resources such as physical memory, 
global selectors, or hardware interrupt vectors. 

If the driver accepts deinstallation, OS/2 will issue the INIT packet to 
the driver waiting for installation. Otherwise, the driver will be treated 
as though it had returned an error at initialization time. 

An OS/2 device driver receives the DEINSTALL packet in ring 0 protect 
mode (in contrast to the INSTALL packet, which was received in ring 3 
protection). The DEINSTALL packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 
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LENGTH. On input, LENGTH is set to ODh, the length of the 
DEINSTALL packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused by the DEINSTALL packet. 

COMMAND. On input, COMMAND is set to 14h, for the DEINSTALL 
strategy packet. 

STATUS. On output, STATUS is set by the driver to lOOh to indicate the 
driver has deinstalled and that the requesting driver may now be issued 
an INIT packet. If the driver refuses the DEINSTALL request, the driver 
returns 8103h in this field (error 3, Unknown Command). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

4.3 Block Device Drivers 

After initialization, removable block device drivers will consider their 
media in uncertain state and will return error 811 Oh (Uncertain Media) 
in response to all strategy packets—except MEDIA CHECK and RESET 
MEDIA. The driver will notify the file manager that the media is uncer¬ 
tain in response to MEDIA CHECK and will retrieve the volume label, 
the format of the BPB for the current media, and the media descriptor 
byte in response to the RESET MEDIA Packet. 

4.3.1 RESET MEDIA (Command 1 lh) 

The file manager indicates to the device driver that the driver’s uncertain 
media state is to be reset. The driver determines the media descriptor 
byte, the BIOS parameter block, and the volume label for the current 
media. This information is saved for use in response to the MEDIA 
CHECK or BUILD BPB strategy packets. The RESET MEDIApacket has 
this format: 

LENGTH 0 BYTE 

UNIT 1 BYTE 

COMMAND 2 BYTE 
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STATUS 3 WORD 

RESERVED 5 DWORD 

LINKAGE 9 DWORD 

LENGTH. On input, LENGTH is set to ODH—the length of the RESET 
MEDIA packet. This value is not to be altered by the device driver. 

UNIT. UNIT is the logical unit number to which the RESET MEDIA 
packet is directed. Multiple logical units may be supported by a block 
device driver. 

COMMAND. On input, COMMAND is set to llh, for the RESET MEDIA 
strategy packet. 

STATUS. On output, STATUS is set by the driver to lOOh to indicate the 
driver has reset the media and that the file manager may now issue 
MEDIA CHECK, BUILD BPB, and other strategy packets. If the driver 
cannot reset the media (open door or defective media), the driver returns 
8102h in this field (error 2, Device Not Ready). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

4.3.2 MEDIA CHECK (Command 1) 

The file manager issues the MEDIA CHECK strategy packet before 
accessing the directory or file allocation table of removable devices. The 
driver determines if the media has been changed and returns a code 
indicating this change. The media descriptor byte of the old media is 
passed to the driver. If, as determined by the driver, the current media’s 
descriptor byte does not coincide with the old descriptor byte, the driver 
indicates that the media has changed. 

The media descriptor byte has a limited set of defined values, so it 
cannot be the only means of determining the media state. Three common - 
means of verifying media changes are used to supplement the media 
descriptor byte. Some controllers provide a changeline flag that senses 
the opening of the drive door. If this flag is raised, the driver indicates the 
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media has changed. If the volume label has been changed, the driver will 
also indicate the media has changed. This method may not be used 
because of the extensive I/O required to check the volume label. If 
sufficient time (about two seconds) has passed between file manager I/O 
requests, the driver can indicate it is uncertain of the media state. Table 
4-3 shows the values of the media descriptor byte. 


Table 4-3: Media Descriptor Byte Values 

VALUE 


DESCRIPTION 

0F8h 


Fixed disk 

0F9h 


1.44M 3-1/2 inch removable diskette 

OFOh 


720K 3-1/2 inch removable diskette 

0F9h 


1.2M 5-1/4 inch removable floppy 

OFDh 


360K 5-1/4 inch removable floppy 

OFFh 


320K 5-1/4 inch removable floppy 

OFCh 


180K 5-1/4 inch removable floppy 

OFEh 


160K 5-1/4 inch removable floppy 

OFFh 


480K 8 inch removable floppy 

OFEh 


240K 8 inch removable floppy 

OFCh 


160K 8 inch removable floppy 

The MEDIA CHECK packet has the following format: 

LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

DESCRIPTOR 

ODh 

BYTE 

RETCODE 

OEh 

BYTE 

LABEL OFFSET 

10h 

WORD 

SEGMENT 

12h 

WORD 


LENGTH. On input, LENGTH is set to 12h, the length of the MEDIA 
CHECK packet. This value is not to be altered by the device driver. 
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UNIT. UNIT is the logical unit number to which the MEDIA CHECK 
packet is directed. Multiple logical units may be supported by a block 
device driver. 

COMMAND. On input, COMMAND is set to 1, for the MEDIA CHECK 
strategy packet. 

STATUS. On output, STATUS is set by the driver to lOOh to indicate the 
driver has determined the media change state and that state has been 
returned in RETCODE. If the driver cannot determine the media change 
state (defective media), the driver returns 810Ch in this field (error OCh, 
General Failure). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

DESCRIPTOR. DESCRIPTOR is set by the file manager to the media 
descriptor returned by the last BUILD BPB or RESET MEDIA packet, 
and which the file manager now considers current. The driver may 
determine the descriptor byte of the current media and compare against 
this value to arrive at the media change state, or use other methods 
(changeline flag, volume label, or a two-second time-out period). 

RETCODE. RETCODE is set by the driver to communicate to the file 
manager the media change status. Value 1 is used to show that the media 
has not changed, and value OFFh is used to communicate that the media 
has changed. If the media change state is uncertain (say, the two-second 
time-out has lapsed), the value 0 is used. 

LABEL. LABEL is a pointer to -the volume label as maintained by the 
device driver. This is the label of the previous media, that was read by the 
device driver in response to a BUILD BPB strategy packet. If use of the 
label is not supported, a pointer to the fixed string "NO NAME" should 
be returned. The label format is an 11 character blank-filled ASCII string, 
followed by a single ASCII NULL (a byte containing 0). 
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4.3.3 BUILD BPB (Command 2) 

The format of the media is defined by the BIOS Parameter Block (BPB). 
The media format was originally defined by the media descriptor byte 
which is now retained for primarily historical reasons. The BPB has itself 
evolved in structure, now allowing for volumes of over 32M bytes in 
length. This new BPB is known as the Extended BPB. See Table 4-4 for 
a complete listing. 


Table 4-4: Extended BPB Format 


FORMAT 

UNIT 

DEFINITION 

Bytes Per Sector 

WORD 

The number of bytes contained in a 
physical sector is set in this word. The 
typical value of this word is 512. 

Sectors Per Cluster 

BYTE 

File space is allocated in clusters of one 
or more sectors. This allocation unit is 
specified here. 

Reserved Sectors 

WORD 

Sectors at the beginning of the volume 
are reserved by the driver for storage of 
boot information and the BPB. 

Number of FATs 

BYTE 

Multiple file allocation tables may be 
maintained by the file management sys¬ 
tem. Although two FATs are normally 
maintained, only one is used. 

Root Dir Entries 

WORD 

The number of directory entries in the 
root directory is specified here. Each 
entry is 32 bytes in length. This field is 
used to calculate the number of sectors 
used to hold the root directory. 

Total Sectors 

WORD 

The total number of sectors on the 
volume is stored here. The extended 

BPB sets its contents to 0 

Media Descriptor 

BYTE 

The media descriptor byte is within this 
byte. 

Sectors Per FAT 

WORD 

The number of sectors contained in the 
file allocation table is specified here. 
One FAT entry exists for each cluster 
on the disk 


0 

This cluster is free 
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Table 4-4: Extended BPB Format 


FORMAT 

UNIT 

DEFINITION 


-16 to -10 

Reserved 


-9 

Bad cluster 


-8 to -1 

End of FAT 

Sectors Per Track 

WORD 

The number of sectors contained in a 
single track of the device is placed here. 

Number Of Heads 

WORD 

The number of heads on the device is 
placed here. 

Hidden Sectors 

DWORD 

The number of sectors from the start of 
the physical device to the start of the 
logical unit is placed here. This is a 
WORD field in the original BPB. 

Large Total Sectors 

DWORD 

The number of sectors on the logical 
unit is placed here, for use by the ex¬ 
tended BPB. This field is not used by 
the original BPB. 


The BUILD BPB packet has the following format: 


LENGTH 

UNIT 

COMMAND 
STATUS 
RESERVED 
LINKAGE 
DESCRIPTOR 
XPER OFFSET 
SEGMENT 
BPB OFFSET 
SEGMENT 


0 

BYTE 

1 

BYTE 

2 

BYTE 

3 

WORD 

5 

DWORD 

9 

DWORD 

ODh 

BYTE 

OEh 

WORD 

lOh 

WORD 

12h 

WORD 

14h 

WORD 


LENGTH. On input, LENGTH is set to 12h, the length of the BUILD 
BPB packet. This value is not to be altered by the device driver. 
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UNIT. UNIT is set on input to the logical unit number to which the 
BUILD BPB packet is directed. Multiple logical units may be supported 
by a block device driver. 

COMMAND. On input, COMMAND is set to 2, for the BUILD BPB 
strategy packet. 

STATUS. On output, STATUS is set by the driver to lOOh to indicate the 
driver has determined the BPB. If the driver cannot determine the BPB 
(defective media), the driver returns 810Ch in this field (error OCh, 
General Failure). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

DESCRIPTOR. DESCRIPTOR is set by the device driver to the media 
descriptor byte. 

XFER. XFER is the address of a sector read by the file manager. This 
address is valid only in strategy context. The sector read by the file 
manager is determined by the IBM bit in the device driver header word. 
If this bit is set (DOS 2.0 format, or more recent), the XFER buffer 
contains the boot sector of the logical unit (first reserved sector). If this 
bit is clear (DOS 1.0 or 1.1), the XFER buffer contains the first sector of 
the FAT. 

BPB. BPB is set by the driver to an address in one of its data segments. 
The buffer address will contain the appropriate BPB, formatted as 
described above. 

4.3.4 REMOVABLE MEDIA (Command OFh) 

If the OPN bit of the device driver header is set, this device driver will 
support removable media, although not all units may actually service 
removable media. The file manager will issue the REMOVABLE MEDIA 
strategy packet to each logical unit supported by the device driver in order 
to determine which logical unit(s) actually maintain removable media. If 
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the OPN bit is clear, the file manager assumes all units are fixed and will 
not issue this I/O packet. 

The BUSY bit in the status word is used to indicate non-removability. 
BUSY bit set by the driver to 1 will indicate to the file manager that the 
logical unit has fixed media, and value 0 will represent removable media. 
The REM OVAB LE MEDIA packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 


LENGTH. LE NGTH is set to ODh, the length of the REMOVABLE 
MEDIA packet, before the strategy routine is called. This value is not to 
be altered by the device driver. 

UNIT. UNIT is set on input to the logical unit number to which the 
REMOVAB LE MEDIA packet is directed. Multiple logical units may be 
supported by a single block device driver. 

COMMAND. On input, COMMAND is set to OFh, for the REMOVABLE 
MEDIA strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate the logical unit has removable media, or to 300h to indicate that 
the logical unit’s media is fixed. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

4.3.5 OPEN (Command ODh) 

The OPEN strategy packet typically is used by the device driver to keep 
track of the number of files open to a logical unit or a device. One reason 
to track open files is to implement file oriented disk caching. Disk caching 
may take place at the file or at logical unit level. Writing of disk sectors 
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might be delayed until file close time or until all files on a logical unit are 
closed, for performance reasons. 


The OPEN packet has the following format: 

LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

FILE# 

ODh 

WORD 


LENGTH. LENGTH is set to OFh, the length of the OPEN packet, before 
the strategy routine is called. This value is not to be altered by the device 
driver. 

UNIT. UNIT is set on input to the logical unit number to which the OPEN 
packet is directed. Multiple logical units may be supported by a single 
block device driver. 

COMMAND. On input, COMMAND is set to ODh, for the OPEN strategy 
packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate the open processing is complete. If the logical unit or the under¬ 
lying physical drive is locked, the driver should return 810Ch (error OCh, 
General Failure) in the STATUS field. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

FILE#. FILE# is a unique value associated by the file manager with the 
file being opened. This value may be used by the device driver for 
file-dependent processing (such as file-oriented caching schemes). 
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4.3.6 CLOSE (Command OEh) 

The CLOSE strategy packet is used to unwind the effect of a previous 
OPEN packet. When a file closes, buffers associated with a caching 
algorithm may be flushed or discarded. 


The CLOSE packet has the following format: 

LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

FILE# 

ODh 

WORD 


LENGTH. LENGTH is set to OFh, the length of the CLOSE packet, before 
calling the strategy routine. This value is not to be altered by the device 
driver. 

UNIT. UNIT is set on input to the logical unit number to which the 
CLOSE packet is directed. Multiple logical units may be supported by a 
single block device driver. 

COMMAND. On input, COMMAND is set to OEh, for the CLOSE 
strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate the close processing is complete. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

FILE#. FILE# is a unique value associated by the file manager with the 
file being opened. This value may be used by the device driver for 
file-dependent processing (such as file-oriented caching schemes). 
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4.3.7 READ (Command 4) 

The READ strategy packet causes the transfer of one or more sectors from 
the block device to a user buffer. The user buffer has been locked and its 
address converted to a physical address. This address is then suitable to 
be mapped at interrupt time, or to be used as target for a DMA tr ans fer 
by the controller. 

The READ strategy packet may request a large number of sectors to 
be read from the logical unit. The driver is not required to transfer more 
than one sector per request and must indicate (in SECTORCOUNT) how 
many sectors it does actually transfer. 

The READ packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

DESCRIPTOR 

ODh 

BYTE 

BUFFER 

OEh 

DWORD 

SECTORCOUNT 

12h 

WORD 

STARTSECTOR 

14h 

DWORD 

FILE# 

18h 

WORD 


LENGTH. LENGTH is set to lAh, the length of the READ packet, before 
calling the strategy routine. This value is not to be altered by the device 
driver. 

UNIT. UNIT is set on input to the logical unit number to which the READ 
packet is directed. Multiple logical units may be supported by a single 
block device driver. 

COMMAND. On input, COMMAND is set to 4, for the READ strategy 
packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate the read processing is complete. If the driver cannot read the 
sector, the driver returns an error code in the STATUS word. If the sector 
number is not supported on the logical unit, return 8108h (error 8, Sector 
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Not Found). If the controller fails on seek, return 8106h (error 6, Seek 
Error). Otherwise, return 810Bh (error OBh, Read Fault) or 810Ch (error 
OCh, General Failure), whichever is most appropriate. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

DESCRIPTOR. DESCRIPTOR is set to the media descriptor byte, and 
is included primarily for historical purposes. Normally, the current BPB 
within the driver was set at receipt of the last BUILD BPB strategy 
packet. 

BUFFER. The file manager sets BUFFER to a 24-bit physical address 
within memory that corresponds to the user buffer. This address is locked 
and translated to a physical address by the file manager before calling 
the strategy routine. 

SECTORCOUNT. SECTORCOUNT is set to the number of sectors the 
device driver is expected to read from the media. The device driver is 
expected to update SECTORCOUNT with the actual number of sectors 
read, if less than the desired count. 

STARTSECTOR. STARTSECTOR is set to the long sector number of the 
first sector to be read from the logical unit. Sector 0 is the first sector 
number on a logical unit, and sectors are numbered consecutively to the 
end of the device. 

FILE#. FILE# is a unique value associated by the file manager with the 
file being read. This value may be used by the device driver for file-de¬ 
pendent processing (such as file-oriented caching schemes). 

4.3.8 WRITE (Command 8) 

The WRITE strategy packet causes transfer of one or more sectors from 
a user buffer to a logical unit of the block device. The user buffer has been 
locked and its address converted to a physical address. This address is 
then suitable to be mapped at interrupt time, or to be used as a target for 
a DMA transfer by the controller. 
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The WRITE strategy packet may request a large number of sectors to 
be written to the logical unit. The driver is not required to transfer more 
than one sector per request, and must indicate (in SECTORCOUNT) how 
many sectors it actually does transfer. 

The WRITE packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

DESCRIPTOR 

ODh 

BYTE 

BUFFER 

OEh 

DWORD 

SECTORCOUNT 

12h 

WORD 

STARTSECTOR 

14h 

DWORD 

FILE# 

18h 

WORD 


LENGTH. LENGTH is set to 1 Ah, the length of the WRITE packet, before 
calling the strategy routine. This value is not to be altered by the device 
driver. 

UNIT. UNIT is set on input to the logical unit number to which the 
WRITE packet is directed. Multiple logical units may be supported by a 
single block device driver. 

COMMAND. On input, COMMAND is set to 8, for the WRITE strategy 
packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate the write processing is complete. If the driver cannot write a 
sector, the driver returns an error code in the STATUS word. If the sector 
number is not supported on the logical unit, return 8108h (error 8, Sector 
Not Found). If the controller fails on seek, return 8106h (error 6, Seek 
Error). Otherwise, return 810Ah (error OAh, Write Fault) or 810Ch (error 
OCh, General Failure), whichever is most appropriate. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 
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DESCRIPTOR. DESCRIPTOR is set to the media descriptor byte, and 
is included primarily for historical purposes. Normally, the current BPB 
within the driver was set at receipt of the last BUILD BPB strategy 
packet. 

BUFFER. BUFFER is set to a 24-bit physical address within memory 
that corresponds to the user buffer. This address is locked and translated 
to a physical address before calling the strategy routine. 

SECTORCOUNT. SECTORCOUNT is set to the number of sectors the 
device driver is expected to write to the media. The device driver is 
expected to update SECTORCOUNT with the actual number of sectors 
written, if less than the desired count. 

STARTSECTOR. STARTSECTOR is set to the long sector number of the 
first sector to be written to the logical unit. Sector 0 is the first sector 
number on a logical unit, and sectors are numbered consecutively to the 
end of the device. 

FILE#. FILE# is a unique value associated by the file manager with the 
file being read. This value may be used by the device driver for file-de¬ 
pendent processing (such as file-oriented cacheing schemes). 

4.3.9 WRITE/VERIFY (Command 9) 

The WRITE/VERIFY strategy packet causes transfer of one or more 
sectors from a user buffer to a logical unit of the block device, it then 
verifies the accuracy of the transfer by reading the data back. 

The user buffer has been locked and its address converted to a physical 
address by the file manager. This address is then suitable to be mapped 
at interrupt time, or to be used as a target for a DMA transfer by the 
controller. Data is transferred from this buffer to the block device. 

The WRITE/VERIFY packet may request a large number of sectors to 
be written to the logical unit. The driver is not required to transfer more 
than one sector per request, and must indicate (in SECTORCOUNT) how 
many sectors it actually does transfer. 

Having written one or more sectors to the block device, the device driver 
is now responsible to verify the integrity of the transfer. Since the driver 
already contains code for writing and reading sectors, the driver writer 
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might want to use the existing routines to perform the write and read 
functions. This is accomplished by allocating an additional strategy 
packet to represent the WRITE function and subsequently to represent 
the READ function. See the accompanying flowchart for det ails 

On entry to the strategy routine, the driver allocates a strategy packet 
(DevHlp function, AllocReqPacket). The driver copies the contents of the 
WRITE/VERIFY packet into the temporary packet, but changes the 
COMMAND byte to WRITE. The driver then calls its own strategy routine 
(with a FAR call). 

On return, the driver checks the DONE bit in the STATUS word of the 
temporary packet. If not set, the driver blocks on the virtual address of 
the packet. When awakened, the driver checks the DONE bit and blocks 
again if the bit is not set. 

When the WRITE request is posted DONE, the driver checks the 
ERROR bit of the temporary packet. If set, the contents of the STATUS 
word of the temporary packet are copied to the WRITE/VERIFY packet, 
the temporary packet is released (DevHlp function, FreeReqPacket), the 
address of the WRITE/VERIFY packet is placed in ES:BX, and the driver 
performs a FAR return. 

If no error took place during the WRITE request, the driver obtains the 
number of sectors written from the SECTORCOUNT field of the tem¬ 
porary packet, copies this number to the WRITE/VERIFY strategy pack¬ 
et, and allocates physical memory of sufficient size to hold that number 
of sectors of data (DevHlp service, AllocPhys). This physical memory 
address is placed in the temporary strategy packet BUFFER doubleword 
and the COMMAND code of the temporary packet is set to READ. The 
driver now calls its.own strategy routine. 

When the driver allocates the physical memory buffer, consideration 
should be given to the eventual comparison of the allocated buffer con¬ 
tents against the user buffer contents. The driver may want to allocate 
the physical buffer in low (below 1M) memory so as to guarantee addres¬ 
sability, or perhaps determine the strategy routine operating mode and 
allocate the memory from low memory if operating in real mode, and 
allocate the memory from high memory if operating in protect mode. 
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Flowchart 4.3.9 
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On return, the driver checks the DONE bit in the STATUS word of the 
temporary packet. If not set, the driver blocks on the virtual address of 
the packet. When awakened, the driver checks the DONE bit, and blocks 
again if necessary. 

When the READ request is posted DONE, the driver checks the ERROR 
bit of the temporary packet. If set, the contents of the STATUS word of 
the temporary packet are copied to the WRITE/VERIFY packet, the 
physical memory buffer is released (DevHlp function, FreePhys), the 
temporary packet is released (DevHlp function, FreeReqPacket), the 
address of the WRITE/VERIFY packet is placed in ES:BX, and the driver 
performs a FAR return. 

If the READ request was successful, the strategy routine may now 
verify the contents of the read data against the contents of the user buffer. 
The driver can map each buffer with DevHlp service, PhysToUVirt, and 
then compares the contents of the two buffers. PhysToUVirt can be used 
for any buffer address if the strategy routine is executing in protect mode, 
and in real mode if both buffer addresses are in the low physical address 
space. This is the justification for allocating the physical buffer in low 
memory if the strategy routine is running in real mode. 

The result of the buffer comparison is recorded in the STATUS word of 
the WRITE/VERIFY packet. If the comparison succeeds, the driver places 
the value lOOh in the STATUS word of the WRITE/VERIFY packet. If the 
comparison fails, the driver places value 810Ah (error OAh, Write Fault), 
value 810Bh (error OBh, Read Fault), or value 810Ch (error OCh, General 
Failure) in the STATUS word of the WRITE/VERIFY packet. 

The driver then releases the selectors it allocated to perform the buffer 
compare (DevHlp function, PhysToUVirt), frees the physical memory 
buffer whose address is in the BUFFER doubleword of the temporary 
strategy packet (DevHlp function, FreePhys), and releases the temporary 
packet (DevHlp function FreeReqPacket). The driver then places the 
virtual address of the strategy packet in ES:BX, and performs a FAR 
return. 

The WRITE/VERIFY packet has the following format: 


LENGTH 

UNIT 

COMMAND 


0 

1 

2 


BYTE 

BYTE 

BYTE 
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STATUS 

RESERVED 

LINKAGE 

DESCRIPTOR 

BUFFER 

SECTORCOUNT 

STARTSECTOR 

FILE# 


3 

WORD 

5 

DWORD 

9 

DWORD 

ODh 

BYTE 

OEh 

DWORD 

12h 

WORD 

14h 

DWORD 

18h 

WORD 


LENGTH. LENGTH is set to lAh, the length of the WRITE/VERIFY 
packet, before calling the strategy routine. This value is not to be altered 
by the device driver. 

UNIT. On entry to the strategy routine, UNIT is set to the logical unit 
number to which the WRITE/VERIFY packet is directed. Multiple logical 
uni ts may be supported by a single block device driver. 

COMMAND. At entry, COMMAND is set to 9, for the WRITE/VERIFY 
strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate the write/verify processing is complete. If the driver cannot write 
a sector or verify its integrity, the driver returns an error code in the 
STATUS word. If the sector number is not supported on the logical unit, 
return 8108h (error 8, Sector Not Found). If the controller fails on seek, 
return 8106h (error 6, Seek Error). Otherwise, return 810Ah (error OAh, 
Write Fault), 810Bh (error OBh, Read Fault), or 810Ch (error OCh, 
General Failure), whichever is most appropriate. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

DESCRIPTOR. DESCRIPTOR is set to the media descriptor byte and 
is included primarily for historical purposes. Normally, the current BPB 
within the driver was set at receipt of the last BUILD BPB strategy 
packet. 
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BUFFER. BUFFER is set to a 24-bit physical address within memory 
that corresponds to the user buffer. This address is locked and translated 
to a physical address before calling the strategy rou tin e. 

SECTORCOUNT. SECTORCOUNT is set to the number of sectors the 
device driver is expected to write to the media. The device driver is 
expected to update SECTORCOUNT with the actual number of sectors 
written, if less than the desired count. 

STARTSECTOR. STARTSECTOR is set to the long sector number of the 
first sector to be written to the logical unit. Sector 0 is the first sector 
number on a logical unit, and sectors are numbered consecutively to the 
end of the device. 

FILE#. FILE# is a unique value associated by the file manager with the 
file being read. This value may be used by the device driver for file-de- 
pendent processing (such as file-oriented caching schemes). 

4.4 The File Manager 

The block device driver provides for multiple physical drives within one 
block driver, and for multiple logical units within a single physical drive. 

The default OS/2 disk driver provides support for a single controller. A 
single (standard) controller can handle four devices: two floppy diskettes 
and two fixed disks. The characteristics of each device may be diff erent 
from all other devices handled by the same controller. Each device is 
represented by the disk driver as a physical drive. 

At driver initialization time, the number and type of devices configured 
on the controller is determined by the device driver. The device driver 
represents diskette devices as a single logical unit per physical drive. The 
device driver reads the partition table of each fixed device to assign logical 
units to a physical drive. The device driver then returns the total number 
of logical units to the file manager. 

The file manager performs I/O to logical units. However, the block 
device driver may be queried by the file manager as to the precise 
configuration of physical drives (strategy packet PARTITIONABLE 
FIXED DISKS) and logical units within the fixed drive (GET FIXED 
DISK/LOGICAL UNIT MAP). 
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4.4.1 PARTITIONABLE FIXED DISKS (Command 16h) 

The PARTITIONABLE FIXED DISKS strategy packet is issued by the 
file manager to determine the number of physical drives supported by the 
block device driver. The device driver is expected to return the total 
number of physical drives it supports. This packet has the following 
format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

COUNT 

ODh 

BYTE 


LENGTH. LENGTH is set to OEh, the length of the PARTITIONABLE 
FIXED DISKS packet, before calling the strategy routine. This value is 
not to be altered by the device driver. 

UNIT. UNIT is not used in this packet. 

COMMAND. COMMAND is set to 016h, for the PARTITIONABLE 
FIXED DISKS strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate processing is complete. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

COUNT. COUNT is set by the device driver to the number of physical 
drivers it supports. 

4.4.2 GET PHYSICAL DISK/LOGICAL UNIT MAP 

The GET FIXED DISK/LOGICAL UNIT MAP (Command 17h) strategy 
packet asks the device driver to return the logical unit map associated 
with a physical drive. The physical drive being queried is placed in the 
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UNIT field of the packet header. The driver returns a bit pattern of its 
logical units associated with the physical drive being queried. 

For example, suppose a driver supports four physical devices: two 
floppy drives, a fixed disk with four partitions, and a fixed disk with three 
partitions. Logical units are numbered within the device driver starting 
at 0, and so the driver would return results as listed in Table 4-5. 


Table 4-5: Sample Logical Unit Numbers _ 

PHYSICAL DRIVE NUMBERS RETURNED BY DRIVER 

0 (Floppy #1) 0 

1 (Floppy #2) 1 

2 (Fixed #1) 2,3,4,5 

3 (Fixed #2) 6,7,8 


The logical unit numbers are returned in a bit map that is 4 bytes in 
length. Bits are numbered in the usual order (right to left) within a byte, 
but bytes are ordered in decreasing significance, opposite to the normal 
80286 doubleword addressing convention. The above example is rewritten 
to illustrate the bit map generation. Table 4-6 lists the physical drives 
and the logical units and unit maps that correspond to them. 


Table 4-6: Sample Logical Unit Maps 


PHYSICAL DRIVE 

LOGICAL UNITS 

LOGICAL UNIT MAP 

0 

0 

DB 0,0,0,1 

1 

1 

DB 0,0,0,2 

2 

2,3,4,5 

DB 0,0,0,3Ch 

3 

6,7,8 

DB 0,0,l,0C0h 


The GET FIXED DISK/LOGICAL UNIT MAP packet has the following 
format: 


LENGTH 

UNIT 

COMMAND 

STATUS 


0 BYTE 

1 BYTE 

2 BYTE 

3 WORD 
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RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

MAP Byte 0 

ODh 

BYTE 

Byte 1 

OEh 

BYTE 

Byte 2 

OFh 

BYTE 

Byte 3 

lOh 

BYTE 


LENGTH. LENGTH is set to llh, the length of the GET FIXED 
DISK/LOGICAL UNIT MAP packet, before calling the strategy routine. 
T his value is not to be altered by the device driver. 

UNIT. UNIT is set to the physical drive number to which the GET FIXED 
DISK/LOGICAL UNIT MAP packet is directed. Multiple physical drives 
are supported by a single block device driver. Each physical drive supports 
multiple logical units. 

COMMAND. COMMAND is set to 17h, for the GET FIXED DISK/LOGI¬ 
CAL UNIT MAP strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate processing is complete. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE is used by the driver strategy queueing routines. 

MAP. MAP is a four-byte logical unit map set by the device driver to notify 
the file manager of the list of logical units supported by the physical drive 
being queried. Logical units 0-7 are indicated by bits set in Byte 3, units 
8-15 are indicated by bits set in Byte 2, units 16-23 are indicated by bits 
set in Byte 1, and units 24-26 are indicated by bits set in Byte 0. The 
small-numbered units are represented by low-order bits of the ap¬ 
propriate byte. 

4.5 Block Device IOCtl Packets 

Certain GENERIC IOCtl strategy packets are defined for use by applica¬ 
tion programs with block device drivers. These are Category 8 IOCtl 
packets, which provide logical unit support and Category 9 IOCtl packets, 
which provide physical drive support. Block device drivers are expected 
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to service these packets, which are generated by low-level format 
programs, disk partitioning programs, bootstrap installation programs, 
and high-level format programs. 

The application program may create a handle to the driver by which 
Category 8 IOCtl packets may be passed to the driver with the DosOpen 
API call with the DASD bit set. A handle for use by Category 9 IOCtl calls 
is created with the API call, DosPhysicalDisk. 

Each GENERIC IOCtl packet contains the virtual address of a 
parameter buffer and a data buffer allocated by the application program. 
In those cases where no parameter or data information is required, the 
application program points these buffers to a single byte of 0. 

Locking of application buffers against swap or motion and the transla¬ 
tion of these buffer addresses for use by the driver in any context other 
than strategy context is the driver’s responsibility. 

Table 4-7 lists the Category 8 IOCtl packets and Table 4-8 lists the 
Category 9 IOCtl packets. 


Table 4-7: Category 8 IOCtl Packets 


PACKET 

Lock Logical Unit 

Unlock Logical Unit 
Block Removable 

Redetermine Media 


Get Device Parameters 


Set Device Parameters 


DESCRIPTION 

Lock logical unit if no files are open on this unit and 
if no lock is current on underlying device. 

Release the lock on this logical unit. 

Indicate to the application whether the device was 
removable media. 

The application indicates it accepts the current 
media for the device. The device driver reads the 
media descriptor byte, the BIOS Parameter Block 
(BPB), and the volume label from the current media 
for the device. 

The device driver returns the BPB for the current 
media. The application may optionally request that 
the driver return the default BPB for the drive. 

The application provides the driver a BPB to be 
used for subsequent I/O calls. The optional requests 
for this call include reset BPB to default BPB, or set 
a new default BPB. 
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Table 4-7: Category 8 IOCtl Packets 

PACKET 

DESCRIPTION 

Write Track 

The application provides the driver with one or 
more consecutive sectors of data within a single 
track, and the sector interleave table. The driver 
writes the sectors in the interleave sequence. 

Read Track 

The application provides the driver with one or 
more consecutive sectors of data within a single 
track, and the sector interleave table. The driver 
reads the sectors in the interleave sequence. 

Verify Track 

The application provides the driver with one or 
more consecutive sectors of data within a single 
track, and the sector interleave table. The driver 
reads the specified track into a driver-provided buff¬ 
er in interleave sequence, and compares its contents 
to the application-provided buffer. 

Format and Verify Track 

The driver formats a track and verifies the track 
after it is formatted. 


Table 4-8: Category 9 IOCtl Packets 


PACKET 

DESCRIPTION 

Lock Physical Drive 

Lock this physical drive only if no files are open on 
any logical unit of the physical drive and if no logi¬ 
cal unit of the physical drive is locked. 

Unlock Physical Drive 

Release the lock of this physical drive. 

Get Physical Parameters 

Return the number of cylinders, heads, and sectors 
per track for this physical drive. 

Physical Write Track 

The application provides the driver with one or 
more consecutive sectors of data within a single 
track, and the sector interleave table. The driver 
writes the sectors in the interleave sequence. 

Physical Read Track 

The application provides the driver with a buffer of 
size sufficient to hold one or more consecutive sec¬ 


tors of data within a single track, and the sector in¬ 
terleave table. The driver reads the sectors in the 
interleave sequence. 
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Table 4-8: Category 9 IOCtl Packets 

PACKET 

DESCRIPTION 

Physical Verify Track 

The application provides the driver with one or 
more consecutive sectors of data within a single 
track, and the sector interleave table. The driver 
reads the specified sector into a driver-provided buff¬ 
er in interleave sequence, and compares its contents 
to the application-provided track buffer. 


4.5.1 Lock Drive (IOCtl 8,0) 

The Lock Drive request will succeed if no files are open to the logical unit 
other than the DASD open by which the Lock Drive request is sent to the 
driver. Lock Drive is handled by the file manager, and is not received by 
the device driver. Its IOCTL packet format is included for reference 
purposes. 

The Lock Drive Generic IOCtl packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 


DATABUFFER 

DB 0 



LENGTH. LENGTH is set to 19h, the length of the Lock Drive IOCtl 
packet. 
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UNIT. UNIT is set to the logical unit number to which the Lock Drive 
IOCtl packet is directed. Multiple logical units may be supported by a 
single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. STATUS is set by the file manager to indicate success or failure 
of the request. 

RESERVED. RESERVED is unused. 

LINKAGE. LINKAGE may be used by the strategy queueing routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 0, for the 
Lock Drive IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the Lock 
Drive function, so this block is defined by the application to contain a 
single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. No data is returned by the Lock 
Drive function, so this block is defined by the application to contain a 
single byte set to 0. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. 

4.5.2 Unlock Drive (IOCtl 8,1) 

The Unlock Drive IOCtl undoes the effect of the Lock Drive IOCtl. Now 
OPEN requests will be forwarded to the device driver. Unlock Drive is 
handled by the file manager, and will not be received by the device driver. 
The Unlock Drive Generic IOCtl packet has the following format: 

LENGTH 0 BYTE 

UNIT 1 BYTE 

COMMAND 2 BYTE 

STATUS 3 WORD 
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\ 


RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 


DATABUFFER 

DB 0 



LENGTH. LENGTH is set to 19h, the length of the Unlock Drive IOCtl 
packet, before calling the strategy routine. 

UNIT. UNIT is set to the logical unit number to which the Unlock Drive 
IOCtl packet is directed. Multiple logical units may be supported by a 
single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. STATUS is set by the file manager to indicate success or failure 
of the request. 

RESERVED. RESERVED is unused. 

LINKAGE. LINKAGE may be used by strategy queueing routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 1, for the 
Unlock Drive IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Unlock Drive function, so this block is defined by the application to 
contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. No data is returned by the Unlock 
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Drive function, so this block is defined by the apphcation to contain a 
single byte set to 0. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the apphcation program. 

4.5.4 Block Removable (IOCtl 8,20h) 

The Block Removable IOCtl is issued by an apphcation to a logical unit 
of a block device driver in order to determine if the media of the logical 
unit is removable. A value is set in the DATABUFFER whose virtual 
address is specified in the IOCtl packet. 

The Block Removable IOCtl packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 . 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 


DATABUFFER 

DB ? 



LENGTH. LENGTH is set to 19h, the length of the Block Removable 
IOCtl packet, before calling the strategy routine. This value is not to be 
altered by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Block Remov¬ 
able IOCtl packet is directed. Multiple logical units may be supported by 
a single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 
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STATUS. Before returning, STATUS is set by the driver to 100h to 
indicate processing is complete. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 20h, for 
the Block Removable IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Block Removable function, so this block is defined by the application to 
contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. A byte value is returned by the 
Block Removable function, so this block is defined by the application to 
contain a single byte. The device driver sets the contents of this buffer to 
0 if the media of this logical unit is removable, and to 1 if this logical unit 
supports fixed media. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value is not 
typically used by the device driver for the Block Removable request. 

4.5.4 Redetermine Media (IOCtl 8,2) 

The Redetermine Media IOCtl is issued when the application has decided 
to accept the current media. The driver is expected to determine the media 
descriptor byte, BPB, and volume label in response to this packet. This 
function is the equivalent of the RESET MEDIA strategy packet. 

The logical unit must have been locked by the application with the Lock 
Drive IOCtl call before Redetermine Media is issued. 

The Redetermine Media IOCtl packet has the following format: 
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LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 


DATABUFFER 

DB 0 



LENGTH. LENGTH is set to 19h, the length of the Redetermine Media 
IOCtl packet, before calling the strategy routine. This value is not to be 
altered by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Redetermine 
Media IOCtl packet is directed. Multiple logical units may be supported 
by a single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate no error took place, and processing is complete. If the logical unit 
had not been locked previously with the Lock Drive IOCtl function, the 
driver sets STATUS to 810Ch (General Failure). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 
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FUNCTION. FUNCTION is set by the application program to 2, for the 
Redetermine Media IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Redetermine Media function, so this block is defined by the application 
to contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. No data is returned by the 
Redetermine Media function, so this block is defined by the application 
to contain a single byte set to 0. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value typically is 
not used by the device driver for locked logical units. 

4.5.5 Get Device Parameters (IOCtl 8,63h) 

The device driver maintains two BPBs for removable devices—the default 
BPB for the drive, and the BPB for the media. The application indicates 
which BPB is to be returned by setting a value in the PARAMETER buffer. 
The device driver returns the BPB and some additional logical unit 
information in the DATABUFFER buffer. 

The Get Device Parameters IOCtl packet has the following format: 


LENGTH 

0 

BYTE 


UNIT 

1 

BYTE 


COMMAND 

2 

BYTE 


STATUS 

3 

WORD 


RESERVED 

5 

DWORD 


LINKAGE 

9 

DWORD 


CATEGORY 

ODh 

BYTE 


FUNCTION 

OEh 

BYTE 


PARAMETER OFFSET 

OFh 

WORD 


SEGMENT 

llh 

WORD 


DATABUFFER OFFSET 

13h 

WORD 


SEGMENT 

15h 

WORD 


FILE# 

17h 

WORD 


PARAMETER 

DB ? 


Value 0 to- request logical 




unit default BPB, 1 for 
current media BPB 
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DATABUFFER DB 31 dup (?) The Extended BPB is 

placed here by driver 

DW ? The number of cylinders 

for the logical unit is 
placed here by driver 

DB ? The device type is placed 

here by driver 

DW ? The device attribute word 

is placed here by driver 


LENGTH. LENGTH is set to 19h, the length of the Get Device 
Parameters IOCtl packet, before calling the strategy routine. This value 
is not to be altered by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Get Device 
Parameters IOCtl packet is directed. Multiple logical units may be sup¬ 
ported by a single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate that processing is complete. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 63h, for 
the Get Device Parameters IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a single byte 
that the application sets to 0 to request the logical unit default BPB, or 1 
to request the BPB of the current media. 
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DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. This buffer is composed of 36 
bytes of data which are returned by the device driver. The first 31 bytes 
of the data buffer are set to the Extended BPB (see Table 4-9). The 
following word is set to the number of cylinders on the logical unit. The 
device type is set in the next byte, and the device attributes are placed in 
the final word of the data buffer. 


Table 4-9: Extended BPB Format 


FORMAT 

UNIT 

DEFINITION 

Bytes Per Sector 

WORD 

The number of bytes contained in a physi¬ 
cal sector is set in this word. The typical 
value of this word is 512. 

Sectors Per 
Cluster 

BYTE 

File space is allocated in clusters of one or 
more sectors. This allocation unit is 
specified here. 

Reserved Sectors 

WORD 

Sectors at the beginning of the volume are 
reserved by the driver for storage of boot 
information and the BPB. 

Number of FATs 

BYTE 

Multiple file allocation tables may be main¬ 
tained by the file management system. Al¬ 
though two FATs are normally maintained, 
only one is used. 

Root Dir Entries 

WORD 

The number of directory entries in the root 
directory is specified here. Each entry is 

32 bytes in length. This field is used to cal¬ 
culate the number of sectors used to hold 
the root directory. 

Total Sectors 

WORD 

The total number of sectors on the volume 
is stored here. The extended BPB sets this 
word to 0 

Media Descriptor 

BYTE 

The media descriptor byte is contained in 
this byte. 

Sectors Per FAT 

WORD 

The number of sectors contained in the file 
allocation table is specified here. One FAT 
entry exists for each cluster on the disk, 
and the entry is 16 bits for larger devices. 


0 

This cluster is free 


-16 to -10 

Reserved 
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Table 4-9: Extended BPB Format 

FORMAT 

UNIT 

DEFINITION 


-9 

Bad cluster 


-8 to -1 

End of FAT 

Sectors Per Track 

WORD 

The number of sectors contained in a 
single track of the device is placed here. 

Number Of Heads 

WORD 

The number of heads on the device is 
placed here. 

Large Total Sec¬ 
tors 

DWORD 

Number of sectors on the logical unit is 
placed here, for use by the extended BPB. 
This field is not used by the original BPB. 

Reserved 

6 BYTES 

Not used at present. 


Eight device types (Table 4-10) are defined for Get Device Parameters. 


Table 4-10: Device Types 

DEVICE 

DESCRIPTION 

0 

48 TPI low density diskette 

1 

96 TPI high density diskette 

2 

3-1/2 inch diskette 

3 

8 inch single density diskette 

4 

8 inch double density diskette 

5 

Fixed Disk 

6 

Tape Drive 

7 

Other 


Two bit flags (Table 4-11) are defined for the Device Attribute word: 
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Table 4-11: Device Bit Flags 

BIT 

DESCRIPTION 

0 

Removable Media flag—The driver returns the con¬ 
tents of the OPN bit of the Device Attribute WORD 
in the device driver header. A 0 in this field to mean 
the device driver supports only fixed media. 

1 

Logical Unit Removability flag—If the driver sup¬ 
ports removable media, this bit is set to indicate to 
the application whether the media of this particular 
logical unit is removable. The driver will set this bit 
to a 1 to indicate fixed media, or to 0 to indicate the 
logical unit’s media is removable. 


FILE# is a unique value associated by the file manager with the IOCtl 
channel opened by the application program. This value is not typically 
used by the device driver for Get Device Parameters. 


4.5.6 Set Device Parameters (IOCtl 8,43h) 

The application may alter any of the parameters associated with a device. 
The BPB is usually altered by an application to specify the parameters 
for a format. Modification of the other parameters is not normally useful, 
and may not be supported. The parameters of the device should be 
recovered with the Get Device Parameters IOCtl call, modified as re¬ 
quired, and then updated with Set Device Parameters by the application, 
so the device driver will not malfunction. 

The device driver maintains two BPBs for removable devices—the 
default BPB for the drive, and the BPB for the media. The application 
may alter either BPB. Altering the default BPB is often meaningless and 
dangerous. The Set Device Parameters IOCtl packet has the following 
format: 


LENGTH 

UNIT 

COMMAND 

STATUS 

RESERVED 


0 BYTE 

1 BYTE 

2 BYTE 

3 WORD 

5 DWORD 
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LINKAGE 

9 

CATEGORY 

ODh 

FUNCTION 

OEh 

PARAMETER OFFSET 

OFh 

SEGMENT 

11 h 

DATABUFFER OFFSET 

13h 

SEGMENT 

15h 

FILE# 

17h 

PARAMETER 

DB ? 


DATABUFFER DB 31 

DW ? 


DB ? 

DW ? 


DWORD 

BYTE 

BYTE 

WORD 

WORD 

WORD 

WORD 

WORD 

The application sets this 
byte to 0 to request the 
BPB from the media, 1 to 
change the default BPB 
for the device, and 2 to 
change the BPP for the 
media 

dup (?) The new Extended BPB is 
placed here by application 

The new number of 
cylinders for the logical 
unit is placed here by ap¬ 
plication 

The new device type is 
placed here by application 

The new device attribute 
word is placed here by ap¬ 
plication 


LENGTH. LENGTH is set to 19h, the length of the Set Device 
Parameters GENERIC IOCtl packet, before calling the strategy routine. 
This value is not to be altered by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Set Device 
Parameters IOCtl packet is directed. Multiple logical units may be sup¬ 
ported by a single block device driver. 

COMMAND. COMMAND is set to lOh for the GENERIC IOCtl strategy 
packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate that processing is complete. 

RESERVED. RESERVED is unused by the driver. 
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LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 43h, for 
the Set Device Parameters IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a single byte 
which the application sets to 0 to revert to building the BPB from the 
media and reset all device parameters, 1 to modify the default BPB of the 
device, and 2 to modify the BPB of the current media. 

DATABUFFER. DATABUFFER is the address of a data block in the 
application program’s data space. This buffer is composed of 36 bytes of 
data which are interpreted as parameters to the device driver. The first 
31 bytes of the data buffer are set to the Extended BPB (see Table 4-12) 
which is to replace the existing BPB. The following word is set to the 
number of cylinders on the logical unit. The device type is set in the next 
byte, and the device attributes are placed in the final word of the data 
buffer. The number of cylinders, device type, and device attributes are to 
replace the existing values. 


Table 4-12: Extended BPB Format 


FORMAT 

UNIT 

DESCRIPTION 

Bytes Per Sector 

WORD 

The number of bytes contained in a physi¬ 
cal sector is set in this word. The typical 
value of this word is 512. 

Sectors Per 
Cluster 

BYTE 

File space is allocated in clusters of one 
or more sectors. This allocation unit is 
specified here. 

Reserved Sectors 

WORD 

Sectors at the beginning of the volume 
are reserved by the driver for storage of 
boot information and the BPB. 

Number of FATs 

BYTE 

Multiple file allocation tables may be 
maintained by the file management sys¬ 
tem. Although two FATs are normally 
maintained, only one is used. 
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Table 4-12: Extended BPB Format 


FORMAT 

UNIT 

DESCRIPTION 

Root Dir Entries 

WORD 

The number of directory entries in the 
root directory is specified here. Each 
entry is 32 bytes in length. This field is 
used to calculate the number of sectors 
used to hold the root directory. 

Total Sectors 

WORD 

The total number of sectors on the 
volume is stored here. The extended BPB 
sets this field to 0 

Media Descriptor BYTE 

The media descriptor byte is contained in 
this byte. 

Sectors Per FAT 

WORD 

The number of sectors contained in the 
file allocation table is specified here. One 
FAT entry exists for each cluster on the 
disk, and the entry is 12 bits long for 
devices under 16M bytes, and 16 bits 
long for larger devices. 


0 

This cluster is free 


-16 to -10 

Reserved 


-9 

Bad cluster 


-8 to -1 

End of FAT 

Sectors Per Track WORD 

The number of sectors contained in a 
single track of the device is placed here. 

Number Of 

Heads 

WORD 

The number of heads on the device is 
placed here. 

Hidden Sectors 

DWORD 

The number of sectors from the start of 
the physical device to the start of the 
logical unit is placed here. This is a 

WORD field in the original BPB. 

Large Total Sec¬ 
tors 

DWORD 

The number of sectors on the logical unit 
is placed here, for use by the extended 
BPB. This field is not used by the 
original BPB. 

Reserved 

6 BYTES 



Eight device types (Table 4-13) are defined for Set Device Parameters. 
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Table 4-13: Set Device Parameters Device Types 

DEVICE 

TYPE 

0 

48 TPI low density diskette 

1 

96 TPI high density diskette 

2 

3-1/2 inch diskette 

3 

8 inch single density diskette 

4 

8 inch double density diskette 

5 

Fixed Disk 

6 

Tape Drive 

7 

Other 

Two bit flags (Table 4-14) are defined for the Device Attribute word. 

Table 4-14: Device Attribute Word Bit Flags 

BIT 

DESCRIPTION 

0 

Removable Media flag—The driver returns the con¬ 
tents of the OPN bit of the Device Attribute word in 
the device driver header. The application will con¬ 
sider a 0 in this field to mean the device driver sup¬ 
ports only fixed media. 

1 

Logical Unit Removability flag—If the driver sup¬ 
ports removable media, this bit is set to indicate to 
the application whether the media of this particular 
logical unit is removable. The driver will set this bit 
to a 1 to indicate fixed media, or to 0 to indicate the 
logical unit’s media is removable. 


FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value is not 
typically used by the device driver Set Device Parameters. 

4.5.7 Write Track (IOCtl 8,44h) 

The Write Track IOCtl is issued when the application has decided to write 
a collection of sectors within a single track to the logical unit. The data 
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buffer pointed to by DATABUFFER contains the sectors to be written in 
sequential logical sector number order. These sectors may be written to 
the track in physical sector number order, or a track layout table may be 
provided by the application to specify a non-sequential ordering of sectors. 

The device driver may handle this request by allocating physical 
memory sufficient to buffer one track, reading the entire track, and then 
placing the desired sectors into the data buffer. The logical unit must have 
been locked by the application with the Lock Drive IOCtl call before Write 
Track is issued. 


The Write Track Generic IOCtl packet has the following format: 

LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB ? 

Command code, a 1- 


flag which indicates to the 
driver whether the track is 
to be written in physical 
sector order ; or if sectors 
are to be numbered accord¬ 
ing to a track layout table . 

DW ? Head number of the 

track to be written 

DW ? Cylinder number of the 

track to be written 


DW ? Starting sector number 

at which the track write 
will start 


DW ? Sector count to be written 
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DATABUFFER 


DW 4*SECT DUP (?) The track layout table is 

composed of a 4-byte entry 
per sector • and one entry 
for each sector within the 
track 

DB TRACK DUP (?) TRACK = length of track 
in bytes. This buffer con¬ 
tains the sector data to be 
written. 


LENGTH. LENGTH is set to 19h, the length of the Write Track IOCtl 
packet, before calling the strategy routine. This value is not to be altered 
by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Write Track 
IOCtl packet is directed. Multiple logical units may be supported by a 
single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
iiidicate no error took place, and processing is complete. If the logical unit , 
had not been locked previously with the Lock Drive IOCtl function, the 
file manager returns error. If I/O error takes place, the driver sets 
STATUS to 810Ah (Write Fault). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical emit control. 

FUNCTION. FUNCTION is set by the application program to 44h, for 
the Write Track IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a one-byte 
command code, a one-word head number, a one-word cylinder number, a 
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one-word starting sector number, a one-word sector count, and a track 
layout table of length 4 bytes per sector in a track. 

Command code is 0 to write sectors in physical sector number order, 
and 1 to write sectors in interleaved order as specified by the track layout 
table. The track layout table is required by the baseline OS/2 disk driver 
even if command code is 0. 

Head number and cylinder number determine the track to be written. 
Starting head number and cylinder number are both 0. 

Starting sector number is the logical sector at which the write is to 
begin. If the track layout table is used to translate the logical sector to a 
physical sector number, this number is looked up in the table. Sector 0 is 
the starting sector. 

Sector count is the number of sectors to be written to the track. Any 
logically sequential number of sectors may be written so long as the write 
does not cross a track boundary. 

The track layout table is a table with one entry for each physical sector 
of the track. The track layout table is indexed by logical sector number. 
Each entry in the table contains the physical sector number and the 
length of that sector. Physical sectors are numbered from 1. Sector lengths 
should be restricted to the same size for compatibility with the file 
manager. The baseline OS/2 device driver passes the track layout table 
to the controller. The format of the Track Layout Table is as follows: 

Logical Sector #0 Physical Sector Number WORD 
Sector Size WORD 

Logical Sector #1 Physical Sector Number WORD 
Sector Size WORD 


Logical Sector #2 Physical Sector Number WORD 
Sector Size WORD 

Logical Sector #n-l Physical Sector Number WORD 
Sector Size WORD 
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DATABUFFER. DATABUFFER is the address of the data to be written. 
Sectors are stored in the data buffer in logical order, and are translated 
into physical order by use of the Track Layout Table. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value is not 
typically used by the device driver for locked logical units. 

4.5.8 Read Track (IOCtl 8,64h) 

The Read Track IOCtl is issued when the application has decided to read 
a collection of sectors within a single track from the logical unit. The data 
buffer pointed to by DATABUFFER will contain the sectors read from the 
track in logical sequential order. These sectors may be read from the track 
in physical sector order or a track layout table may be provided by the 
application to specify a non-sequential logical ordering of sectors. 

The device driver may handle this request by allocating physical 
memory that is sufficient to buffer one track, reading the entire track, 
and by then placing the desired sectors into the data buffer. 

The logical unit must have been locked by the application with the Lock 
Drive IOCtl call before Read Track is issued. The Read Track Generic 
IOCtl packet has the following format: 


LENGTH 

0 

BYTE 


UNIT 

1 

BYTE 


COMMAND 

2 

BYTE 


STATUS 

3 

WORD 


RESERVED 

5 

DWORD 


LINKAGE 

9 

DWORD 


CATEGORY 

ODh 

BYTE 


FUNCTION 

OEh 

BYTE 


PARAMETER OFFSET 

OFh 

WORD 


SEGMENT 

llh 

WORD 


DATABUFFER OFFSET 
SEGMENT 15h 

FILE# 17h 

PARAMETER DB ? 

13h 

WORD 

WORD 

WORD 

A 1-byte flag which indi¬ 
cates to the driver whether 
the sectors are to be read 
in physical order ■ or if sec¬ 
tors are to be read accord¬ 
ing to a track layout table 
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/ 


DW ? The head number of the 

track to be read 

DW ? The cylinder number of 

the track to be read 

DW ? The number of the sector 

where the track read will 
start 

DW ? The number of sectors to 

be read 

DW 4*SECT DUP (?) The track layout table is 

composed of a 4-byte entry 
per sector\ and one entry 
for each sector within the 
track 

DATABUFFER DB TRACK DUP (?) TRACK = length of track 

t in bytes—this buffer will 

contain the sectors read 
from the track. 

LENGTH. LENGTH is set to 19h, the length of the Read Track IOCtl 
packet, before calling the strategy routine. This value is not to be altered 
by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Read Track 
IOCtl packet is directed. Multiple logical units may be supported by a 
single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate no error took place, and processing is complete. If the logical unit 
had not been locked previously with the Lock Drive IOCtl function, the 
file manager will return error. If I/O error takes place, the driver sets 
STATUS to 810Ah (Write Fault). 

RESERVED. RESERVED is unused by the driver. 

LINEAGE. LINKAGE may be used by the driver strategy queueing 
routines. 
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CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 64h, for 
the Read Track IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a one-byte 
command code, a one-word head number, a one-word cylinder number, a 
one-word starting sector number, a one-word sector count, and a optional 
track layout table of length 4 bytes per sector in a track. 

Command code is 0 to read sectors in physical sector number order, and 
1 to read sectors in interleaved order as specified by the track layout table. 
The track layout table is required by the baseline OS/2 disk driver even 
if command code is 0. 

Head number and cylinder number determine the track to be read. 
Starting head number and cylinder number are both 0. 

Starting sector number is the logical sector where the read is to begin. 
If the track layout table is used to translate the logical sector to a physical 
sector number, this number is looked up in the table. Sector 0 is the 
starting sector. 

Sector count is the number of sectors to be read from the track. Any 
logically sequential number of sectors may be written as long as the read 
does not cross a track boundary. 

The track layout table is a table with one entry for each physical sector 
of the track. The track layout table is indexed by logical sector number. 
Each entry in the table contains the physical sector number and the 
length of that sector. Physical sectors are numbered from 1. Sector lengths 
should be restricted to the same size for compatibility with the file 
manager. The baseline OS/2 device driver passes the track layout table 
to the controller. The format of the Track Layout Table is as follows: 


Logical Sector #0 Physical Sector Number WORD 

Sector Size WORD 

Logical Sector #1 Physical Sector Number WORD 

Sector Size WORD 
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Logical Sector #2 

Physical Sector Number 

WORD 

Sector Size 

WORD 

Logical Sector #n-l 

Physical Sector Number 

WORD 

Sector Size 

WORD 


DATABUFFER. DATABUFFER is the address into which the driver is 
to place the sectors read. Sectors are stored in the data buffer in logical 
order and are translated into physical order by the Track Layout Table. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value is not 
typically used by the device driver for locked logical units. 

4.5.9 Verify Track (IOCtl 8,65h) 

The Verify Track IOCtl is issued when the application has decided to 
verify the integrity of a collection of sectors within a single track from the 
logical unit. The data buffer pointed to by DATABUFFER will contain the 
sectors to be validated in logical sequential order. These sectors may be 
represented on the track in physical sector order, or a track layout table 
may he provided by the application to specify a non-sequential logical 
ordering of sectors. 

The device driver may handle this request by allocating physical 
memory sufficient to buffer one track, reading the entire track, and then 
verifying the required sectors in the data buffer. The logical unit must 
have been locked by the application with the Lock Drive IOCtl call before 
Verify Track is issued. 

The Verify Track Generic IOCtl packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

FUNCTIONCATEGORY 

ODh 

BYTE 

FUNCTIONCODE 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 
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SEGMENT 

DATABUFFER OFFSET 
SEGMENT 

FILE# 

PARAMETER 

llh 

13h 

15h 

17h 

DB ? 

WORD 

WORD 

WORD 

WORD 

A 1-byte flag which indi¬ 
cates to the driver whether 
the sectors are verified in 
physical order .; or if sec¬ 
tors are to be numbered ac¬ 
cording to a track layout 
table 


DW ? 


The head number of the 
track to be verified 


DW ? 


The cylinder number of 
the track to be verified 

• 

DW ? 


The number of the sector 
where the track verify will 
start 


DW ? 


The number of sectors to 
be verified 


DW 4*SECT DUP(?) 

The track layout table is 
composed of a 4-byte entry 
per sector ; and one entry 
for each sector within the 
track 

DATABUFFER 

DB TRACK DUP(?) 

TRACK = length of track 
in bytes. This buffer will 
contain the sector data to 
be compared against the 
data on the track. 


LENGTH. LENGTH is set to 19h, the length of the Verify Track IOCtl 
packet; before calling the strategy routine. This value is not to be altered 
by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Verify Track 
IOCtl packet is directed. Multiple logical units may be supported by a 
single block device driver. 
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COMMAND. The file manager sets COMMAND to lOh, for the IOCtl 
strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate no error took place, and that processing is complete. If the logical 
unit ha d not been locked previously with the Lock Drive IOCtl function, 
the file manager returns error. If an I/O error takes place or if the compare 
fails, the driver will set STATUS to 810Bh (Read Fault). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LIN KAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 65h, for 
the Verify Track IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a one-byte 
command code, a one-word head number, a one-word cylinder number, a 
one-word starting sector number, a one-word sector count, and a track 
layout table of length 4 bytes per sector in a track. 

Command code is 0 to read/verify sectors in physical sector number 
order, and 1 to read/verify sectors in interleaved order as specified by the 
track layout table. The track layout table is required by the baseline OS/2 
disk driver even if command code is 0. 

Head number and cylinder number determine the track to be verified. 
Starting head number and cylinder number are both 0. 

Starting sector number is the logical sector at which the read/verify is 
to begin. If the track layout table is used to translate the logical sector to 
a physical sector number, this number is looked up in the table. Sector 0 
is the starting sector. 
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Sector count is the number of sectors to be verified from the track. Any 
logically sequential number of sectors may be written as long as the read 
does not cross a track boundary. 

The track layout table is a table with one entry for each physical sector 
of the track. The track layout table is indexed by logical sector number. 
Each entry in the table contains the physical sector number and the 
length of that sector. Physical sectors are numbered from 1. Sector lengths 
should be restricted to the same size for compatibility with the file 
manager. The baseline OS/2 device driver passes the track layout table 
to the controller. The format of the Track Layout Table is as follows: 


Logical Sector #0 

Physical Sector Number 
Sector Size 

WORD 

WORD 

Logical Sector #1 

Physical Sector Number 
Sector Size 

WORD 

WORD 

Logical Sector #2 

Physical Sector Number 
Sector Size 

WORD 

WORD 

Logical Sector #n-l 

Physical Sector Number 
Sector Size 

WORD 

WORD 


DATABUFFER. DATABUFFER is the address of the sector data to be 
verified. Sectors are stored in the data buffer in logical order, and are 
translated into physical order by use of the Track Layout Table. This data 
is then compared against the data read from the device. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. T his value is not 
typically used by the device driver for locked logical units. 

4.5.10 Format and Verify Track (IOCtl 8,45h) 

The Format and Verify Track IOCtl is issued when the application has 
decided to format a collection of sectors within a single track on the logical 
unit. These sectors may be formatted on the track in physical sector 
number order, or a format track table may be provided by the application 
to specify a non-sequential ordering of sectors. 
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The logical uni t must have been locked by the application with the Lock 
Drive IOCtl call before Format and Verify Track is issued. The Format 
and Verify Track Generic IOCtl packet has the following format: 


LENGTH 

UNIT 

COMMAND 

STATUS 

RESERVED 

LINKAGE 

CATEGORY 

FUNCTION 

PARAMETER OFFSET 
SEGMENT 

0 BYTE 

1 BYTE 

2 BYTE 

3 WORD 

5 DWORD 

9 DWORD 

ODh BYTE 

OEh BYTE 

OFh WORD 

llh WORD 


DATABUFFER OFFSET 
SEGMENT 

FILE# 

13h WORD 

15h WORD 

17h WORD 


PARAMETER 

DB ? 

A 1-byte flag that indi¬ 
cates to the driver whether 
the track is to be for¬ 
matted in physical sector 
order • or if sectors are to 
be numbered according to 
a track layout table 

- 

DW ? 

The head number of the 
track to be formatted 


DW ? 

The cylinder number of 
the track to be formatted 


DW ? 

The number of the sector 
at which the track format 
will start 


DW ? 

The number of sectors to 
be formatted 


DW 4*SECT DUP (?) The format track table is 
composed of a 4-byte entry 
per sector ; and one entry 
for each sector within the 
track 


DATABUFFER 


DB 0 
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LENGTH. LENGTH is set to 19h, the length of the Format and Verify 
Track IOCtl packet, before calling the strategy routine. This value is not 
to be altered by the device driver. 

UNIT. UNIT is set to the logical unit number to which the Format and 
Verify Track IOCtl packet is directed. Multiple logical units may be 
supported by a single block device driver. 

COMMAND. The file manager sets COMMAND to lOh, for the IOCtl 
strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate no error took place and processing is complete. If the logical unit 
had not previously been locked with the Lock Drive IOCtl function, the 
file manager returns error. If I/O error takes place, the driver sets 
STATUS to 810Ah (Write Fault). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. FUNCTION is set by the application program to 8, for 
Category 8 IOCtl. Category 8 IOCtls are reserved for logical unit control. 

FUNCTION. FUNCTION is set by the application program to 45h, for 
the Format and Verify Track IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a one-byte 
command code, a one-word head number, a one-word cylinder number, a 
one-word starting sector number, a one-word sector count, and a format 
track table of length 4 bytes per sector in a track. 

Command code is 0 for format sectors in physical sector number order, 
and 1 for format sectors in interleaved order as specified by the format 
track table. 
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Cylinder number and head number select the track to be formatted. 
Star ting head number and cylinder number are both 0. 

Starting sector number is the logical sector at which the format is to 
begin. If the format track table is used, this number is used as an index 
into the table. Sector 0 is the starting sector. 

Sector count is the number of sectors to be formatted to the track. Any 
logically sequential number of sectors may be formatted as long as the 
format operation does not cross a track boundary. 

Format track table is a table with one entry for each physical sector of 
the track. The format track table is indexed by logical sector number. Each 
entry in the table contains the cylinder number, head number, logical 
sector number corresponding to the physical sector, and a length code for 
that sector. Sector lengths should be restricted to the same size for 
compatibility with the file manager. The sector size code is defined in 
Table 4-15. 


Table 4-15: Sector Size Codes 

CODE 

SECTOR SIZE 

0 

128 

1 

256 

2 

512 

3 

1024 


The format track table is always required by the OS/2 baseline device 
driver. The format track table is passed to the controller dining the format 
operation. 

The format of the format track table is as follows: 

Logical Sector #0 Cylinder Number BYTE (actual length 10 bits) 

Head N umb er BYTE (actual length 6 bits) 

Physical Sector Number BYTE 
Sector Size Code BYTE 

Logical Sector #1 Cylinder Number BYTE 
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Head Number BYTE 

Physical Sector Number BYTE 
Sector Size Code BYTE 

Logical Sector #2 Cylinder Number BYTE 

Head Number BYTE 

Physical Sector Number BYTE 
Sector Size Code BYTE 

Logical Sector #n-l Cylinder Number ' BYTE 
Head Number BYTE 

Physical Sector Number BYTE 
Sector Size Code BYTE 


DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. No data is returned by the 
Format and Verify Track function, so this block is defined by the applica¬ 
tion to contain a single byte set to 0. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value is not 
typically used by the device driver for locked logical units. 


4.5.11 Lock Physical Drive (IOCtl 9,0) 

The Lock Physical Drive request will succeed if no files are open to any . 
logical unit of the physical device, and no lock is pending on any logical 
unit. Lock Physical Drive is handled by the file manager, and is not 
received by the device driver. Its format is included for reference purposes. 
The Lock Physical Drive Generic IOCtl packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 
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FILE# 

17h WORD 

PARAMETER 

DB 0 

DATABUFFER 

DB 0 


LENGTH. LENGTH is set to 19h, the length of the Lock Physical Drive 
IOCtl packet, before calling the strategy routine. 

UNIT. UNIT is set to the physical unit number to which the Lock Physical 
Drive IOCtl packet is directed. Multiple physical devices may be sup¬ 
ported by a single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. STATUS is set by the file manager to indicate success or failure 
of the request. 

RESERVED. RESERVED is unused. 

LINKAGE. LINKAGE may be used by strategy queueing routines. 

CATEGORY. CATEGORY is set by the application program to 9, for 
Category 9 IOCtl. Category 9 IOCtls are reserved for physical device 
control. 

FUNCTION. FUNCTION is set by the application program to 0, for the 
Lock Physical Drive IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the Lock 
Physical Drive function, so this block is defined by the application to 
contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. No data is returned by the Lock 
Physical Drive function, so this block is defined by the application to 
contain a single byte set to 0. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. 



162 WRITING OS/2 DEVICE DRIVERS 


4.5.12 Unlock Physical Drive (IOCtl 9,1) 

The Unlock Physical Drive IOCtl undoes the effect of the Lock Physical 
Drive IOCtl. Now file OPEN requests issued to logical uni ts on the 
physical device will be forwarded to the device driver. Unlock Physical 
Drive is handled by the file manager, and will not be received by the device 
driver. The Unlock Physical Drive Generic IOCtl packet has the follow ing 
format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 


DATABUFFER 

DB 0 



LENGTH. LENGTH is set to 19h, the length of the Unlock Physical Drive 
IOCtl packet, before calling the strategy routine. 

UNIT. UNIT is set to the physical unit number to which the Lock Physical 
Drive IOCtl packet is directed. Multiple physical devices may be sup¬ 
ported by a single block device driver. 

COMMAND. The file manager sets COMMAND to lOh, for the IOCtl 
strategy packet. 

STATUS. STATUS is set by the file manager to indicate success or failure 
of the request. 

RESERVED. RESERVED is unused. 

LINKAGE. LINKAGE may be used by strategy queueing routines. 
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CATEGORY. CATEGORY is set by the application program to 9, for 
Category 9 IOCtl. Category 9 IOCtls are reserved for physical drive 
control. 

FUNCTION. FUNCTION is set by the application program to 1, for the 
Unlock Physical Drive IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Unlock Drive function, so this block is defined by the application to 
contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space. No data is returned by the Unlock 
Drive function, so this block is defined by the application to contain a 
single byte set to 0. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. 

4.5.13 Get Device Parameters (IOCtl 9,63h) 

Get Device Parameters is issued when the application wants to know the 
characteristics of the physical device. The driver returns the number of 
cylinders, heads, and number of sectors per track to the application. The 
Get Device Parameters Generic IOCtl packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 
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PARAMETER 

DB 0 


DATABUFFER 

DW? 

reserved 


DW ? 

Number of Cylinders of 
physical drive, returned 
by device driver 


DW ? 

Number of Heads of physi¬ 
cal drive, returned by 
device driver 


DW ? 

Number of Sectors per 
Track of physical drive, 
returned by device driver 


DB 8 DUP (?) 

reserved 


LENGTH. LENGTH is set to 19h, the length of the Get Device 
Parameters GENERIC IOCtl packet, before calling the strategy routine. 
This value is not to be altered by the device driver. 

UNIT. UNIT is set to the physical unit number to which the Get Device 
Parameters IOCtl packet is directed. Multiple physical devices may be 
supported by a single block device driver. 

COMMAND. The file manager sets COMMAND to lOh, for the IOCtl 
strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate the Get Device Parameters processing is complete. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by strategy queueing routines. 

CATEGORY. CATEGORY is set by the application program to 9, for 
Category 9 IOCtl. Category 9 IOCtls are reserved for physical drive 
control. 

FUNCTION. FUNCTION is set by the application program to 63h, for 
the Get Device Parameters IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the Get 
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Device Parameters function, so this block is defined by the application to 
contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a returned data block 
in the appbcation program’s data space. This data block contains device 
configuration data returned by the device driver. The format of the data 
buffer is as follows: 

Reserved WORD 

Number of Cylinders WORD 

Number of Heads WORD 

Number of Sectors per Track WORD 
Reserved 8 BYTES 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. 

4.5.14 Physical Write Track (IOCtl 9,44h) 

The Physical Write Track IOCtl is issued when the application has 
decided to write a collection of sectors within a single track to the logical 
unit. The data buffer pointed to by DATABUFFER contains the sectors 
to be written in logical sector number order. Sectors may be written to the 
track in physical sector number order, or a track layout table may be 
provided by the appbcation to specify non-sequential ordering of sectors. 

The device driver may handle this request by allocating physical 
memory sufficient to buffer one track, reading the entire track, placing 
the desired sectors in the data buffer into the track buffer, and writing 
the track buffer back to the device. The physical drive has been locked by 
the appbcation with the Lock Physical Drive IOCtl call before Physical 
Write Track is issued. 

The Physical Write Track Generic IOCtl packet has the following 
format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 
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CATEGORY 

ODh. BYTE 


FUNCTION 

OEh BYTE 


PARAMETER OFFSET 

OFh WORD 


SEGMENT 

llh WORD 


DATABUFFER OFFSET 

13h WORD 


SEGMENT 

15h WORD 


FILE# 

17h WORD 


PARAMETER 

DB ? 

A 1-byte flag which indi¬ 
cates to the driver whether 
the track is to be written 
in physical sector order ■ or 
if sectors are to be se¬ 
quenced according to a 
track layout table 


DW ? 

The head number of the 
track to be written 


DW ? 

The cylinder number of 
the track to be written 


DW ? 

The number of the sector 
where the track write will 
start 


DW ? 

The number of sectors to 
be written 


DW 4*SECT DUP(?) 

The track layout table is 
composed of a 4-byte entry 
per sector ; and one entry 
for each sector within the 
track 

DATABUFFER 

DB TRACKDUP (?) 

TRACK = length of track 
in bytes. This buffer con¬ 
tains the sector data to be 
written. 


LENGTH. LENGTH is set to 19h, the length of the Physical Write Track 
IOCtl packet, before calling the strategy routine. This value is not to be 
altered by the device driver. 


UNIT. UNIT is set to the physical unit number to which the Physical 
Write Track IOCtl packet is directed. Multiple physical devices may be 
supported by a single block device driver. 
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COMMAND. The file manager sets COMMAND to lOh, for the IOCtl 
strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate no error took place and processing is complete. If the physical 
device had not been locked previously with the Lock Physical Drive IOCtl 
the file manager returns error. If I/O error takes place, the driver sets 
STATUS to 810Ah (Write Fault). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 9, for 
Category 9 IOCtl. Category 9 IOCtls are reserved for physical drive 
control. 

FUNCTION. FUNCTION is set by the application program to 44h, for 
the Physical Write Track IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a one-byte 
command code, a one-word head number, a one-word cylinder number, a 
one-word starting sector number, a one-word sector count, and a track 
layout table of length 4 bytes per sector in a track. 

Command code is 0 for write sectors in physical sector number order, 
and 1 for write sectors in interleaved order as specified by the track layout 
table. The OS/2 baseline disk driver requires the track layout table in 
either case. 

Cylinder number and head number select the track to be written. 
Starting head number and cylinder number are both 0. 

Starting sector number is the logical sector at which the write is to 
begin. If the track layout table is used to translate the logical sector to a 
physical sector number, this number is used as index into the table. Sector 
0 is the starting sector. 
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Sector count is the number of sectors to be written to the track. Any 
logically sequential number of sectors may be written so long as the write 
does not cross a track boundary. 

Track layout table is a table with one entry for each physical sector of 
the track. Each entry in the table contains the physical sector number 
corresponding to the logical sector number, and the length of that sector. 
Physical sector numbers start at 1. Sector lengths should be restricted to 
the same size for compatibility with the file manager. The track layout 
table is passed by the baseline OS/2 device driver to the controller. The 
format of the track layout table is as follows: 


Logical Sector #0 
Logical Sector #1 
Logical Sector #2 


Physical Sector Number WORD 
Sector Size WORD 

Physical Sector Number WORD 
Sector Size WORD 

Physical Sector Number WORD 
Sector Size WORD 


Logical Sector #n-l Physical Sector Number WORD 
Sector Size WORD 


DATABUFFER. DATABUFFER is the virtual address of the data to be 
written. Sectors are stored in the data buffer in logical sector number 
order, and are translated into physical order by use of the track layout 
table. If this address is to be used at a time other than strategy time, the 
driver must lock this buffer and ensure its addressability in the other 
contexts. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value is not 
typically used by the device driver for physical units. 

4.5.15 Physical Read Track (IOCtl 9,64h) 

The Physical Read Track IOCtl is issued when the application has decided 
to read a collection of sectors within a single track from a physical drive. 
The data buffer pointed to by DATABUFFER will contain the sectors read 
from the track in logical sector number order. These sectors may be read 
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from the track in physical sector order, or a track layout table may be 
provided by the application in order to specify a non-sequential logical 
ordering of sectors. 

The device driver may handle this request by allocating physical 
memory sufficient to buffer one track, reading the entire track, and then 
placing the desired sectors into the data buffer. The physical drive must 
have been locked by the application with the Physical Lock Drive IOCtl 
call before Physical Read Track is issued. 

The Physical Read Track Generic IOCtl packet has the following 


format: 


LENGTH 0 

UNIT 1 

COMMAND 2 

STATUS 3 

RESERVED 5 

LINKAGE 9 

CATEGORY ODh 

FUNCTION OEh 

PARAMETER OFFSET OFh 

SEGMENT llh 

DATABUFFER OFFSET 13h 
SEGMENT 15h 

FILE# 17h 

PARAMETER DB ? 


DW ? 

DW ? 

DW ? 


DW ? 


BYTE 

BYTE 

BYTE 

WORD 

DWORD 

DWORD 

BYTE 

BYTE 

WORD 

WORD 

WORD 

WORD 

WORD 

A 1-byte flag that indi¬ 
cates to the driver whether 
the sectors are to be read 
in physical order , or if sec¬ 
tors are to be read accord¬ 
ing to a track layout table 

The head number of the 
track to be read 

The cylinder number of 
the track to be read 

The number of the sector 
at which the track read 
will start 

The number of sectors to 
be read 
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DW 4*SECT DUP (?) The track layout table is 
composed of a 4-byte entry 
per sector\ and one entry 
for each sector within the 
track 

DATABUFFER DB TRACK DUP (?) TRACK = length of track 

in bytes . This buffer will 
contain the sectors read 
from the track . 


LENGTH. LENGTH is set to 19h, the length of the Physical Read Track 
IOCtl packet, before calling the strategy routine. This value is not to be 
altered by the device driver. 

UNIT. UNIT is set to the physical unit number to which the Physical 
Read Track IOCtl packet is directed. Multiple physical devices may be 
supported by a single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate no error took place and processing is complete. If the physical 
drive had not been locked previously with the Lock Physical Drive IOCtl 
the file manager returns error. If I/O error takes place, the driver sets 
STATUS to 810Bh (Read Fault). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 9, for 
Category 9 IOCtl. Category 9 IOCtls are reserved for physical drive 
control. 

FUNCTION. FUNCTION is set by the application program to 64h, for 
the Physical Read Track IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a one-byte 
command code, a one-word head number, a one-word cylinder number, a 
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one-word starting sector number, a one-word sector count, and a track 
layout table of length 4 bytes per sector in a track. 

Command code is 0 for read sectors in physical sector number order, 
and 1 for read sectors in interleaved order specified by the track layout 
table. The OS/2 baseline disk driver needs a track layout table in either 
case. _ 

Cylinder number and head number select the track from which data 
is to be read. Starting head number and cylinder number are both 0. 

Starting sector number is the logical sector where the read is to begin. 
If the track layout table is used to translate the logical sector to a physical 
sector number, this number is used as an index into the table. Sector 0 is 
the starting sector. 

Sector count is the number of sectors to be read from the track. Any 
logically sequential number of sectors may be read as long as the read 
does not cross a track boundary. 

Track layout table is a table with one entry for each physical sector of 
the track. Each entry in the table contains the physical sector number 
corresponding to the logical sector number and the length of that sector. 
Physical sector numbers start at 1. Sector lengths should be restricted to 
the same size for compatibility with the file manager. The track layout 
table is passed by the baseline OS/2 device driver to the controller. The 
format of the track layout table is as follows: 


Logical Sector #0 
Logical Sector #1 
Logical Sector #2 


Physical Sector Number WORD 
Sector Size WORD 

Physical Sector Number WORD 
Sector Size WORD 

Physical Sector Number WORD 
Sector Size WORD 


Logical Sector #n-l Physical Sector Number WORD 
Sector Size WORD 


DATABUFFER. DATABUFFER is the address into which the driver 
places the read sectors. Sectors are stored in the data buffer in logical 
sector number order, and are translated into physical order by use of the 
track layout table. 
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FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value typically is 
not used by the device driver for physical drives. 


4.5.16 Physical Verify Track (IOCtl 9,65h) 

The Physical Verify Track IOCtl is issued when the application has 
decided to verify the integrity of a collection of sectors within a single 
track from the physical drive. The data buffer pointed to by DATABUF- 
FER will contain the sectors to be validated in logical sector number order. 
These sectors may be represented on the track in physical sector order, 
or a track layout table may be provided by the application to specify a 
non-sequential logical ordering of sectors. 

The device driver may handle this request by allocating physical 
memory sufficient to buffer one track, reading the entire track, and then 
verifying the required sectors in the data buffer. The physical drive must 
have been locked by the application with the Physical Lock Drive IOCtl 
call before Physical Verify Track is issued. 

The Physical Verify Track Generic IOCtl packet has the following 
format: 


LENGTH 

0 

BYTE 


UNIT 

1 

BYTE 


COMMAND 

2 

BYTE 


STATUS 

3 

WORD 


RESERVED 

5 

DWORD 


LINKAGE 

9 

DWORD 


CATEGORY 

ODh 

BYTE 


FUNCTION 

OEh 

BYTE 


PARAMETER OFFSET 

OFh 

WORD 


SEGMENT 

llh 

WORD 


DATABUFFER OFFSET 

13h 

WORD 


SEGMENT 

15h 

WORD 


FILE# 

17h 

WORD 


PARAMETER 

DB ? 


A 1-byte flag that indi¬ 
cates to the driver whether 
the sectors are verified in 
physical order\ or if sec¬ 
tors are to be numbered ac¬ 
cording to a track layout 
table 
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DW ? 

DW ? 

DW ? 

DW ? 


The head number of the 
track to be verified 

The cylinder number of 
the track to be verified 

The number of the sector 
where the track verify will 
start 

The number of sectors to 
be verified 


DW 4*SECT DUP (?) The track layout table is 
composed of a 4-byte entry 
per sector * and one entry 
for each sector within the 
track 

DATABUFFER DB TRACK DUP (?) TRACK = length of track 

in bytes—this buffer will 
contain the sector data to 
be compared against the 
data on the track 


LENGTH. LENGTH is set to 19h, the length of the Physical Verify Track 
IOCtl packet, before calling the strategy routine. This value is not to be 
altered by the device driver. 

UNIT. UNIT is set to the physical unit number to which the Physical 
Verify Track IOCtl packet is directed. Multiple physical devices may be 
supported by a single block device driver. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate no error took place and processing is complete. If the physical 
drive had not been locked previously with the Physical Lock Drive IOCtl 
file manager returns error. If I/O error takes place or if the compare fails, 
the driver sets STATUS to 810Bh (read Fault). 

RESERVED. RESERVED is unused by the driver. 
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LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to 9, for 
Category 9 IOCtl. Category 9 IOCtls are reserved for physical drive 
control. • 

FUNCTION. FUNCTION is set by the application program to 65h, for 
the Physical Verify Track IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. This buffer is composed of a one-byte 
command code, a one-word head number, a one-word cylinder number, a 
one-word starting sector number, a one-word sector count, and a track 
layout table of length 4 bytes per sector in a track. 

Command code is 0 for read/verify sectors in physical sector number 
order, and 1 for read/verify sectors in interleaved order as specified by the 
track layout table. The OS/2 baseline disk driver requires a track layout 
table in either case. 

Cylinder number and head number select the track from which data 
is to be verified. Starting head number and cylinder number are both 0. 

Starting sector number is the logical sector where the read/verify is to 
begin. If the track layout table is used to translate the logical sector to a 
physical sector number, this number is used as an index into the table. 
Sector 0 is the starting sector. 

Sector count is the number of sectors to be read and verified from the 
track. Any logically sequential number of sectors may be read as long as 
the read does not cross a track boundary. 

Track layout table is a table with one entry for each physical sector of 
the track. Each entry in the table contains the physical sector number 
corresponding to the logical sector number and the length of that sector. 
Physical sector numbers start at 1. Sector lengths should be restricted to 
the same size for compatibility with the file manager. The track layout 
table is passed by the baseline OS/2 device driver to the controller. The 
format of the track layout table is as follows: 
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Logical Sector #0 
Logical Sector #1 
Logical Sector #2 


Physical Sector Number WORD 
Sector Size WORD 

Physical Sector Number WORD 
Sector Size WORD 

Physical Sector Number WORD 
Sector.Size WORD 


Logical Sector #n-l Physical Sector Number WORD 
Sector Size WORD 


DATABUFFER. DATABUFFER is the address of the sector data to be 
verified. Sectors are stored in the data buffer in logical sector number 
order, and are translated into physical order by use of the track layout 
table. This data is then compared against the data read from the device. 

FILE#. FILE# is a unique value associated by the file manager with the 
IOCtl channel opened by the application program. This value typically is 
not used by the device driver for physical units. 


4.6 Character Device Drivers 

The character device driver model is much simpler than the block device 
driver model. Character device drivers are opened, after which read and 
write requests are honored. Input and output device status may be 
queried as to whether the device is idle. Input or output queues may be 
flushed. The driver may then be closed. 

Character device drivers optionally support monitors. Monitor chains 
are opened, and monitor threads are registered to the chain. All monitor 
threads associated with a process are eventually deregistered, and the 
monitor chain is closed. Monitor support is provided with strategy packets 
and generic IOCtls. 

4.6.1 Device OPEN (Command ODh) 

The device driver may arbitrate ownership of its device internally, or it 
may allow the file manager to perform this arbitration. The SHR bit of 
the device header should be set if file manager sharing is desired. 

Character device drivers often choose to arbitrate device ownership 
rather than accepting the file system rules because the file system 
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requires cooperation from the processes competing for ownership for 
orderly device sharing. 

If the device driver arbitrates device ownership, it uses the OPEN and 
CLOSE packets to determine this ownership. If no OPENs are current on 
the device, the device is considered available for ownership. On receipt of 
an OPEN packet, the character device driver determines the process 
number of the calling process, and assigns ownership of the device to that 
process. Subsequent OPEN requests from other processes are refused. 
Subsequent OPEN requests from the same process increment an owner¬ 
ship usage count. This ownership count is decremented for each CLOSE 
request from the same process, and the device becomes free when this 
count goes to zero. 

The character device driver must test the MON bit (bit 3) of the 
STATUS word on input to determine if this packet is a Device OPEN 
request, or a Monitor OPEN request. This bit will be zero for a Device 
OPEN request. The OPEN packet has the following format: 


LENGTH 

UNIT 

COMMAND 

STATUS 

RESERVED 

LINKAGE 

FILE# 


0 BYTE 

1 BYTE 

2 BYTE 

3 WORD 

5 DWORD 

9 DWORD 

ODh WORD 


LENGTH. On input, LENGTH is set to OFh, the length of the OPEN 
packet. T his value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. On input, COMMAND is set to ODh, for the OPEN strategy 
packet. 

STATUS. The MON bit (bit 3) of the STATUS word is zero for the Device 
OPEN command. Before returning, the driver sets STATUS to lOOh if the 
OPEN request was accepted, or 810Ch (error OCh, General Failure) if the 
OPEN request was rejected. 

RESERVED. RESERVED is unused by the driver. 
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LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

4.6.2 Device CLOSE (Command OEh) 

Character device drivers often choose to arbitrate device ownership 
rather than accepting the file system rules. This is because the file system 
requires cooperation from the processes that are competing in order to 
obtain ownership for orderly device sharing. 

If the device driver arbitrates device ownership, it uses the OPEN and 
CLOSE packets to determine this ownership. If no OPENs are current on 
the device, the device is considered available for ownership. On receipt of 
an OPEN packet, the character device driver determines the process 
number of the calling process and assigns ownership of the device to that 
process. Subsequent OPEN requests from other processes are refused. 
Subsequent OPEN requests from the same process increment an owner¬ 
ship usage count. This ownership count is decremented for each CLOSE 
request from the same process and the device becomes free when this 
count goes to zero. 

The character device driver must test the MON bit (bit 3) of the 
STATUS word on input to determine if this packet is a Device CLOSE 
request or a Monitor CLOSE request. This bit will be zero for a Device 
CLOSE request. The CLOSE packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

FILE# 

ODh 

WORD 


LENGTH. On input, LENGTH is set to OFh, the length of the CLOSE 
packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. On input, COMMAND is set to OEh, for the CLOSE 
strategy packet. 
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STATUS. The MON bit (bit 3) of the STATUS word is zero for the Device 
CLOSE command. Before returning, the driver sets STATUS to lOOh to 
indicate completion of the CLOSE operation. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 


4.6.3 READ (Command 4) 

The READ request is issued to the device driver to cause transfer of data 
from the device to a user buffer. The physical address of the user buffer 
and the buffer length are specified. The driver reads data, places it in the 
buffer, and returns the actual count of characters read (typically less than 
the buffer length). The driver returns a character count of 0 to indicate 
end-of-file condition. The READ packet has the following format: 


LENGTH 

UNIT 

COMMAND 

STATUS 

RESERVED 

LINKAGE 

DESCRIPTOR 

BUFFER 

BYTECOUNT 

STARTSECTOR 

FILE# 


0 

BYTE 

1 

BYTE 

2 

BYTE 

3 

WORD 

5 

DWORD 

9 

DWORD 

ODh 

BYTE 

OEh 

DWORD 

12h 

WORD 

14h 

DWORD 

18h 

WORD 


LENGTH. On input, LENGTH is set to lAh, the length of the READ 
packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. On input, COMMAND is set to 4, for the READ strategy 
packet. 

STATUS. Before returning, STATUS is set to lOOh to indicate successful 
completion of the READ request, or to 810Bh (Read Fault) to indicate an 
error in the read. 
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RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

DESCRIPTOR. DESCRIPTOR is unused for character devices. 

BUFFER. BUFFER contains a 24-bit physical address within memory 
which corresponds to the user buffer. The virtual address of BUFFER is 
locked and translated to a physical address before the strategy routine is 
called. 

BYTECOUNT. On input, the file manager has set BYTECOUNT to the 
length of BUFFER—the maximum count of characters which may be read 
from the device. Before returning, the device driver sets BYTECOUNT to 
the n umb er of characters catually read from the device and placed in 
BUFFER. The end-of-file condition is signalled by placing a zero in 
BYTECOUNT. 

STARTSECTOR. STARTSECTOR is unused for character devices. 

FILE#. FILE# is a unique value associated by the file manager with the 
handle used to generate this READ request. This value is not typically 
used by character device drivers. 

4.6.4 WRITE (Command 8) 

The WRITE request is issued to the device driver to cause transfer of data, 
from a user buffer to the device. The physical address of the user buffer 
and the number of bytes to be written are specified. The driver writes the 
data from the buffer to the device, and returns the actual count of 
characters written (usually equal to the requested number). If the number 
of characters written is less than the request count, the OS/2 error 
handler may report a "short count" error. The WRITE packet has the 


following format: 



LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

.WORD 

RESERVED 

5 

DWORD 
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LINKAGE 

9 

DWORD 

DESCRIPTOR 

ODh 

BYTE 

BUFFER 

OEh 

DWORD 

BYTECOUNT 

12h 

WORD 

STARTSECTOR 

14h 

DWORD 

FILE# 

18h 

WORD 


LENGTH. On input LENGTH is set to lAh, the length of the WRITE 
packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. On input, COMMAND is set to 8, for the WRITE strategy 
packet. 

STATUS. Before returning, STATUS is set to lOOh to indicate successful 
completion of the WRITE request, or to 810Ah (error OAh, Write Fault) 
to indicate an error in the read. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

DESCRIPTOR. DESCRIPTOR is unused for character devices. 

BUFFER. BUFFER is set to a 24-bit physical address within memory 
which corresponds to the user buffer. The virtual address of BUFFER is 
locked and translated to a physical address before the strategy routine is 
called. 

BYTECOUNT. On input, the file manager has set BYTECOUNT to the 
number of characters in BUFFER to be written to the device. Before 
returning, the device driver sets BYTECOUNT to the number of charac¬ 
ters actually written to the device from BUFFER. If the count of charac¬ 
ters actually written is not equal to the requested length, an error may 
be reported by the system error handler. 

STARTSECTOR. STARTSECTOR is unused for character devices. 

FILE#. FILE# is a unique value associated by the file manager with the 
handle used to generate this WRITE request. This value is not typically 
used by character device drivers. 
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4.6.5 NONDESTRUCTIVE READ NO WAIT (Command 5) 

This packet determines what, if any, first character is waiting in the 
device driver buffer to be read. This character is not removed from the 
driver buffer, and the next READ packet to be serviced will return this 
character. The NONDESTRUCTIVE READ NO WAIT packet has the 
following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

RETURNEDCHAR 

ODh 

BYTE 


LENGTH. On input, LENGTH is set to OEh, the length of the NON¬ 
DESTRUCTIVE READ NO WAIT packet. This value is not to be altered 
by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. COMMAND is set to 5, for the NONDESTRUCTIVE READ 
NO WAIT strategy packet. 

STATUS. Before returning, the device driver sets STATUS to 300h if the 
input buffer is empty, or lOOh if the input buffer contains at least one 
character and the first waiting character is returned in RETURNED- 
CHAR. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

RETURNEDCHAR. RETURNEDCHAR is set by the device driver to 
the first character waiting in the device input queue, if the queue is not 
empty. 
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4.6.6 INPUT STATUS (Command 6) 

The device driver sets the STATUS word to indicate whether its input 
queue is empty, or if there is at least one character waiting to be read. The 
effect of this call is to guarantee that a subsequent READ request will be 
serviced immediately. The INPUT STATUS packet has the following 
format: 


LENGTH ' 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 


LENGTH. On input, LENGTH is set to ODh, the length of the INPUT 
STATUS packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. COMMAND is set to 6, for the INPUT STATUS strategy 
packet. 

STATUS. Before returning, the device driver sets the STATUS word to 
300h if the input queue is empty, or to lOOh if at least one character is 
waiting in the input queue to be read. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

4.6.7 OUTPUT STATUS (COMMAND OAh) 

The device driver sets the STATUS word to indicate whether a WRITE 
request is pending for the device, or if the device is currently idle. The 
effect of this packet is to determine if a WRITE request will be immedi¬ 
ately serviced, or if it will have to wait for service. The OUTPUT STATUS 
packet has the following format: 

LENGTH 0 BYTE 

UNIT 1 BYTE 

COMMAND 2 BYTE 
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STATUS 3 WORD 

RESERVED 5 DWORD 

LINEAGE 9 DWORD 

LENGTH. On input, LENGTH is set to ODh, the length of the OUTPUT 
STATUS packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. COMMAND is set to OAh, for the OUTPUT STATUS 
strategy packet. 

STATUS. Before returning, the device driver sets the STATUS word to 
300h if the device is currently busy, or to lOOh if a subsequent WRITE 
packet can expect to be serviced immediately. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

4.6.8 INPUT FLUSH (Command 7) 

The device driver is expected to terminate all pending READ requests, 
flush any internal input queues, and flush any monitor input queues. The 
driver terminates pending READ strategy packets by settingthe STATUS 
word of the READ packet to 8111h (error llh, Character I/O Call Inter¬ 
rupted), and either unblocking the READ strategy thread or issuing 
DevDone for the packet (depending on the READ strategy routine’s 
blocking strategy). The INPUT FLUSH packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 


LENGTH. On input, LENGTH is set to ODh, the length of the INPUT 
FLUSH packet. This value is not to be altered by the device driver. 
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UNIT. UNIT is unused for character devices. 

COMMAND. COMMAND is set to 7, for the INPUT FLUSH strategy 
packet. 

STATUS. Before returning, after having flushed all characters in the 
input queue and after having terminated all pending READ requests, the 
device driver sets the STATUS word to lOOh to indicate completion of the 
INPUT FLUSH function. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

4.6.9 OUTPUT FLUSH (Command OBh) 

The device driver is expected to terminate all pending WRITE requests, 
flush any internal output queues, and flush any monitor output queues. 
The driver terminates pending WRITE strategy packets by setting the 
STATUS word of the WRITE packet to 8111h (error llh, Character I/O 
Call Interrupted), and either unblocking the WRITE strategy thread or 
issuing DevDone for the packet (depending on the WRITE strategy 
routine’s blocking strategy). The OUTPUT FLUSH packet has the follow¬ 
ing format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 


LENGTH. On input, LENGTH is set to ODh, the length of the OUTPUT 
FLUSH packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. COMMAND is set to OBh, for the OUTPUT FLUSH 
strategy packet. 
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STATUS. Before returning, after having flushed all characters in the 
output queue and after having terminated all pending WRITE requests, 
the device driver sets the STATUS word to lOOh to indicate completion of 
the OUTPUT FLUSH function. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 


4.6.10 Monitor OPEN (Command ODh) 

The character device driver must test the MON bit (bit 3) of the STATUS 
word on input to determine if this packet is a Device OPEN request or a 
Monitor OPEN request. This bit will be 1 for a Monitor OPEN request. A 
Monitor OPEN request is issued on behalf of a process that wishes to 
register monitor threads to the device (API call DosMonOpen). Only one 
Monitor OPEN is issued by a process to a device. 

The device driver will often create a monitor chain for this process. 
Subsequent Register a Monitor IOCtl packets are used to add monitor 
threads to this chain . These monitor threads remain on the chain until a 
Monitor CLOSE packet is received by the device driver, at which time all 
monitor threads associated with the process are deregistered, and the 


chain is destroyed. 


The Monitor OPEN packet has the following format: 

LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

FILE# 

ODh 

WORD 


LENGTH. On input, LENGTH is set to OFh, the length of the Monitor 
OPEN packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. On input, COMMAND is set to ODh, for the Monitor OPEN 
strategy packet. 



186 WRITING OS/2 DEVICE DRIVERS 


STATUS. The MON bit (bit 3) of the STATUS word is one for the Monitor 
OPEN command. Before returning, the driver sets STATUS to lOOh to 
indicate successful processing of the Monitor OPEN request. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

FILE#. FILE# is set to a unique number associated with the monitor 
handle of the process. FILE# typically is not used for character monitor 
operations. 

4.6.11 Monitor CLOSE (Command OEh) 

The character device driver must test the MON bit (bit 3) of the STATUS 
word on input to determine if this packet is a Device CLOSE request or 
a Monitor CLOSE request. This bit will be 1 for a Monitor CLOSE request. 
The Monitor CLOSE request is issued in response to API call DosMon- 
Close, or when a process terminates with an open monitor handle. 

On receipt of a Monitor CLOSE packet, the driver deregisters all 
monitor threads for the process issuing the packet. The driver then 
deletes any chains it may have created for this process. The Monitor 
CLOSE packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

FILE# 

ODh 

WORD 


LENGTH. On input, LENGTH is set to OFh, the length of the Monitor 
CLOSE packet. This value is not to be altered by the device driver. 

UNIT. UNIT is unused for character devices. 

COMMAND. COMMAND is set to OEh, for the Monitor CLOSE strategy 
packet. 
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STATUS. The MON bit (bit 3) of the STATUS word is one for the Monitor 
CLOSE command. Before returning, the driver sets STATUS to lOOh to 
indicate completion of the Monitor CLOSE operation. 

RESERVED. RESERVED is unused by the driver. 

FILE#. FILE# is set to a unique number associated with the monitor 
handle of the process. FILE# typically is not used for character monitor 
operations. 

4.7 IOCtl Character Device Support 

Certain GENERIC IOCtl strategy packets are defined for use by applica¬ 
tions in conjunction with character device drivers. These functions divide 
into two groups: monitor support and queue flush support. 

IOCtl monitor functions are not reproduced in strategy packets. These 
functions are Query Monitor Support and Register a Monitor. In par¬ 
ticular, registration of a character monitor can only be done by means of 
the Register a Monitor IOCtl packet. The DosMonReg API call is trans¬ 
lated into this IOCtl call. 

The queue flush IOCtl calls, Flush Input Queue and Flush Output 
Queue reproduce the functionality of the INPUT FLUSH and OUTPUT 
FLUSH strategy packets. 

4.7.1 Query Monitor Support (IOCtl OBh, 60h) 

The application issues this IOCtl to determine if the device provides 
character monitor support. The driver indicates device support by return¬ 
ing a code in the STATUS word. 

The Query Monitor Support Generic IOCtl packet has the following 
format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 
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FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh. 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DBO 


DATABUFFER 

DBO 



LENGTH. LENGTH is set to 19h, the length of the Query Monitor 
Support IOCtl packet, before the strategy routine is called. This value is 
not to be altered by the device driver. 

UNIT. UNIT is not used by character devices. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate that it provides monitor support. If the driver does not provide 
monitor support the driver should set STATUS to 8112h (Monitors Not 
Supported). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to OBh, for 
Category OBh IOCtl. Category OBh IOCtls are reserved for character 
device control. 

FUNCTION. FUNCTION is set by the application program to 60h, for 
the Query Monitor Support IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Query Monitor Support function, so this block is defined by the applica¬ 
tion to contain a single byte set to 0. 
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DATABUFFER. DATABUFFER is the address of a returned data block 
in the application program’s data space; No data is returned by the Query 
Monitor Support function, so this block is defined by the application to 
contain a single byte set to 0. 

FILE#. FILE# is set to a unique number associated with the monitor 
handle of the process. FILE# is not typically used for character monitor 
operations. 


4.7.2 Register a Monitor (IOCtl OAh, 40h) 

An application requests registration of a monitor thread with the Register 
a Monitor IOCtl packet. A monitor thread is associated with an input 
buffer and output buffer, its position in the monitor chain, and a driver- 
defined index word used to indicate to the driver on which chain this 
monitor is to be registered. 

The Register a Monitor Generic IOCtl packet has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 



DATABUFFER 

DW? 

The PLACEMENTFLAG 
word is used to indicate 
where in the chain this 
monitor is to he placed . 


DW ? 
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The INDEX word has 
driver-defined meaning, 
and is often used to select 
one of many monitor chains 

The INPUTOFFSET word 
contains the offset of the 
monitor thread input buffer 

The BUFFERSELECTOR 
word contains the selector 
value of the monitor 
thread input and output 
buffers—both input and 
output buffers are con¬ 
strained to reside in the 
same segment 

The OUTPUTOFFSET 
word contains the offset of 
the monitor thread output 
buffer 

LENGTH. LENGTH is set to 19h, the length of the Register a Monitor 
IOCtl packet, before the strategy routine is called. This value is not to be 
altered by the device driver. 

UNIT. UNIT is not used by character devices. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, STATUS is set by the driver to lOOh to 
indicate that it has successfully registered the monitor thread. If the 
application has 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to OAh, for 
Category OAh IOCtl. Category OAh IOCtls are reserved for character 
device monitor control. 

FUNCTION. FUNCTION is set by the application program to 40h, for 
the Register a Monitor IOCtl. 


dw ? 


dw ? 


dw ? 
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PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Register Monitor function, so this block is defined by the application to 
contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a data block in the 
application program’s data space. This data block contains five 
parameters set by the application: PLACEMENTFLAG, INDEX, IN- 
PUTOFFSET, BUFFERSELECTOR, and OUTPUTOFFSET. 

PLACEMENTFLAG. PLACEMENTFLAG is set by the application to 
request a preferred position in the monitor chain. The application may 
request the driver to register the monitor at the default, front, or back 
position of the monitor chain. Value 0 in PLACEMENTFLAG requests 
placement at the default position in the monitor chain. Value 1 in 
PLACEMENTFLAG requests the driver register the monitor thread at 
the head of the monitor chain. Value 2 in PLACEMENTFLAG requests 
monitor thread placement at the end of the monitor chain. The value in 
PLACEMENTFLAG is passed to the DevHlp call Register, which will 
perform the placement function. 

INDEX. INDEX is set by the application to a value that is defined by the 
device driver. This value typically is used by the driver to select the chain 
on which the monitor thread is to be registered. An example of the use of 
the INDEX word might be to choose registration of the monitor thread to 
the input or the output monitor chain for full-duplex devices. 

INPUTOFFSET. INPUTOFFSET is the offset of the input buffer as¬ 
sociated with the monitor thread. Each monitor thread is associated with 
both an input and output buffer. Character packets are written to the 
input buffer by the monitor dispatcher, which then activates the monitor 
thread. The monitor thread writes character packets to the output buffer 
before suspending. The monitor dispatcher then forwards these character 
packets to the next monitor thread in the chain. The device driver will 
not need to access this virtual address. 

BUFFERSELECTOR. BUFFERSELECTOR is the selector value for 
both the input and output buffers associated with the monitor thread. 
Both input and output buffers must reside in the same segment. 
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OUTPUTOFFSET. OUTPUTOFFSET is the offset of the output buffer 
associated with the monitor thread. The monitor thread will write char¬ 
acter packets to the output buffer, which will be copied to the input buffer 
of the next monitor thread on the chain. The device driver will not need 
to access this virtual address. 

FILE#. FILE# is set to a unique number associated with the monitor 
handle of the process. FILE# is not typically used for character monitor 
operations. 

4.7.3 Flush Input Buffer (IOCtl OBh, 1) 

The device driver is expected to terminate all pending READ requests, 
flush any internal input queues, and flush any monitor input queues. The 
driver terminates pending READ strategy packets by setting the STATUS 
word of the READ packet to 8111h (error llh, Character I/O Call Inter¬ 
rupted), and either unblocking the READ strategy thread or issuing 
DevDone for the packet (depending on the READ strategy routine’s 
blocking strategy). 

The Flush Input Buffer IOCtl duplicates the function of the strategy 
packet INPUT FLUSH. The Flush Input Buffer Generic IOCtl packet has 
the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 


DATABUFFER 

DB 0 
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LENGTH. LENGTH is set to 19h, the length of the Flush Input Buffer 
IOCtl packet, before the strategy routine is called. This value is not to be 
altered by the device driver. 

UNIT. UNIT is not used by character devices. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, but after having flushed all characters in the 
input queue and after having terminated all pending READ requests, the 
device driver sets the STATUS word to lOOh to indicate completion of the 
Flush Input Buffer function. 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LIN KAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to OBh, for 
Category OBh IOCtl. Category OBh IOCtls are reserved for character 
device control. 

FUNCTION. FUNCTION is set by the application program to 1, for the 
Flush Input Buffer IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Flush Input Buffer function, so this block is defined by the application to 
contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a data block in the 
application program’s data space. No data is returned by the Flush Input 
Buffer function, so this block is defined by the application to contain a 
single byte set to 0. 

FILE#. F ILE # is set to a unique number associated with the monitor 
handle of the process. FILE# is not typically used for character monitor 
operations. 
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4.7.4 Flush Output Buffer (IOCtl OBh, 2) 

The device driver is expected to terminate all pending WRITE requests, 
flush any internal input queues, and flush any monitor input queues. The 
driver terminates pending WRITE strategy packets by setting the 
STATUS word of the WRITE packet to 8111h (error llh, Character I/O 
Call Interrupted), and either unblocking the WRITE strategy thread or 
issuing DevDone for the packet (depending on the WRITE strategy 
routine’s blocking strategy). 

The Flush Output Buffer IOCtl duplicates the function of the strategy 
packet OUTPUT FLUSH. The Flush Output Buffer Generic IOCtl packet 
has the following format: 


LENGTH 

0 

BYTE 

UNIT 

1 

BYTE 

COMMAND 

2 

BYTE 

STATUS 

3 

WORD 

RESERVED 

5 

DWORD 

LINKAGE 

9 

DWORD 

CATEGORY 

ODh 

BYTE 

FUNCTION 

OEh 

BYTE 

PARAMETER OFFSET 

OFh 

WORD 

SEGMENT 

llh 

WORD 

DATABUFFER OFFSET 

13h 

WORD 

SEGMENT 

15h 

WORD 

FILE# 

17h 

WORD 

PARAMETER 

DB 0 


DATABUFFER 

DB 0 



LENGTH. LENGTH is set to 19h, the length of the Flush Output Buffer 
IOCtl packet, before the strategy routine is called. This value is not to be 
altered by the device driver. 

UNIT. UNIT is not used by character devices. 

COMMAND. COMMAND is set to lOh, for the IOCtl strategy packet. 

STATUS. Before returning, after having flushed all characters in the 
output queue and after having terminated all pending WRITE requests, 



STRATEGY PACKET DETAILS 195 


the device driver sets the STATUS word to lOOh to indicate completion of 
the Flush Output Buffer function. 

RES ER VED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to OBh, for 
Category OBh IOCtl. Category OBh IOCtls are reserved for character 
device control. 

FUNCTION. FUNCTION is set by the application program to 2, for the 
Flush Output Buffer IOCtl. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s data space. No parameters are required by the 
Flush Output Buffer function, so this block is defined by the application 
to contain a single byte set to 0. 

DATABUFFER. DATABUFFER is the address of a data block in the 
application program’s data space. No data is returned by the Flush 
Output Buffer function, so this block is defined by the application to 
contain a single byte set to 0. 

FILE#. F ILE # is set to a unique number associated with the monitor 
handle of the process. FILE# is not typically used for character monitor 
operations. 

4.8 GENERIC IOCtls 

Two general types of GENERIC IOCtls are supported by device drivers: 
system-defined IOCtls and user-defined IOCtls. BysteimdefinedJO.Ctl 
category codes range from 0 to 1-27, and .user=defined IOGtl'category codes~ 
are chosen by the driver writer from the range 128 through 255; 

System-defined IOCtls are divided into general classes of device sup¬ 
port. Each class of device is assigned an IOCtl category code by the system. 
If a device driver expects to function with application software written 
for a class of device it manages, it should provide support for those IOCtl 
functions. The driver writer must code his strategy routines while con- 
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sidering that access to an unlocked virtual address may result in blocking 
of the strategy routine (if the virtual address is not present in RAM). 

Error codes returned to system-defined IOCtls are translated by the 
kernel into OS/2 error codes. System defined IOCtls (see Table 4-16) are 
supported by character device drivers, with the exception of Category 8 
(Logical Disk Control) and Category 9 (Physical Drive Control) IOCtls. 


Table 4-16: System-defined IOCtl Category Codes 

CODE 

IOCtl CODE 

1 

Serial Device Control 

3 

Pointer Draw Control 

4 

Keyboard Control 

5 

Printer Control 

3 

Light Pen 

7 

Mouse Control 

8 

Logical Disk Control 

9 

Physical Drive Control 

OAh 

Character Monitor Control 

OBh 

Character Device Control 


User-defined IOCtls have PARAMETER and DATABUFFER buffer 
formats defined by the device driver. These user-defined IOCtl calls will 
only be made by application programs specifically engineered to take 
advantage of these custom driver features. The driver writer must be 
aware that reference to an unlocked virtual address will result in the 
blocking of the strategy routine if the virtual memory is not present in 
RAM. 

User-defined IOCtls normally are serviced by character device drivers. 
Character device drivers have a simple interface to the file manager which 
makes them easier to write and generally more flexible. Drivers that 
support primarily IOCtl packets would be configured as character drivers. 
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Error codes returned by the device driver to a user-defined GENERIC 
IOCtl packet are returned to the application without translation (except 
for ORing the value OFFOOh with the error code). Thus user-defined OS/2 
error codes are returned by the driver in response to an IOCtl packet, and 
not the driver error codes that would be returned in other strategy 
packets. 


4.8.1 Format of GENERIC IOCtl Packets 

IOCtl packets share the following format: 


LENGTH 

0 

BYTE 


UNIT 

1 

BYTE 


COMMAND 

2 

BYTE 


STATUS 

3 

WORD 


RESERVED 

5 

DWORD 


LINKAGE 

9 

DWORD 


CATEGORY 

ODh 

BYTE 


FUNCTION 

OEh 

BYTE 


PARAMETER OFFSET 

OFh 

WORD 


SEGMENT 

llh 

WORD 


DATABUFFER OFFSET 

13h 

WORD 


SEGMENT 

15h 

WORD 


FILE# 

17h 

WORD 


PARAMETER 

DB ? 

DUP (?) 


DATABUFFER 

DB ?DUP (?) 

The device driver assigns 
a length and format to the 
parameter buffer and the 
data buffer . The virtual ad¬ 
dresses of the parameter 
and data buffers are acces¬ 
sible in the context of the 
strategy routine. These buf¬ 
fers must be locked and 
made addressable to be 
used in interrupt context. 


LENGTH. LENGTH is set to 19h, the length of the GENERIC IOCtl 
packet, before the strategy routine is called. This value is not to be altered 
by the device driver. 
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UNIT. UNIT is not used by character devices. 

COMMAND. COMMAND is set to lOh, for the GENERIC IOCtl strategy 
packet. 

STATUS. The STATUS field is set before the strategy routine returns 
(terminates). The value lOOh is placed in the STATUS word to indicate 
that the request terminated without error. If the Category Code 
(CATEGORY) or Function Code (FUNCTION) of the IOCtl packet are not 
supported by the driver, the driver sets STATUS to 8103h (Unknown 
Command). If an error code is reported, the application receives the error 
code ORed with the value OFFOOh (and without other translation). 

RESERVED. RESERVED is unused by the driver. 

LINKAGE. LINKAGE may be used by the driver strategy queueing 
routines. 

CATEGORY. CATEGORY is set by the application program to the 
driver-defined IOCtl Category Code. 

FUNCTION. FUNCTION is set by the application program to the driver- 
defined IOCtl Function Code. 

PARAMETER. PARAMETER is the address of a parameter block in the 
application program’s address space. The size and format of the 
parameter block are defined by the device driver. The address of this 
buffer is a virtual address, addressable in strategy context (although the 
strategy routine will block if the virtual memory is not in RAM when 
addressed). If this buffer is to be accessible at other than strategy time, 
the driver must ensure addressability of the buffer at that time. Typically, 
the driver will lock the buffer and convert its address to a 24-bit physical 
address which can be mapped when needed. 

DATABUFFER. DATABUFFER is the address of a data block in the 
application program’s address space. The size and format of the data block 
are defined by the device driver. The address of this buffer is a virtual 
address, addressable in strategy context. If this buffer is to be accessible 
at other than strategy time, the driver must ensure addressability of the 
buffer at that time. Typically, the driver will lock the buffer and convert 
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its address to a 24-bit physical address which can be mapped when 
needed. 

FILE#. FILE# is set to a unique number associated with the IOCtl handle 
of the process. FILE# is not typically used for IOCtl requests. 




CHAPTER 5 


DEVICE HELPER ROUTINES 


Device helper routines provide OS/2 services to the device driver, which 
is not permitted to make API calls (except at initialize time). The address 
of the device helper routine is a tiled address, valid in both protect- and 
real-mode contexts. This address is contained in the strategy INIT packet 
and must be saved by the device driver for use in strategy or interrupt 
context. The device helper function code is placed in DL by the driver 
before calling the helper service entry point. 

Each device driver is associated with a main code and a main data 
segment. Many of the device helper routines require that DS contain the 
address (in the current real/protect context) of the main data segment. 
The value of DS is used to identify the strategy routine to the kernel. 
Routines which need to identify the strategy routine typically start 
additional contexts (interrupt, timer, and notification). The value in DS 
will be converted to the correct value in the real/protect context of the 
started routine. 

Different device helper routines are available at different points in the 
driver. At initialization time, helper routines that queue packets, block, 
manage semaphores, or manage character monitors cannot be used 
because the initialization process is single-threaded. In interrupt context, 
helper routines that wait or alter interrupt vectors may not be used. 
Virtually every device helper function is available to the strategy routine. 
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5.1 Device Helper Address 

At initialize time, the driver is called at the strategy routine entry point 
with ES:BX pointing to the init packet. The (far) address of the device 
helper interface is located at an offset of 14 bytes into the packet. The 
following code might be used to extract the address and place it in location 


DevHlp: 



MOV 

AX,word ptr ES:[BX+14] 

offset word of address 

MOV 

word ptr DevHlp,AX 


MOV 

AX,word ptr ES:[BX+16] 

segment word of address 

MOV 

word ptr DevHlp+2,AX 



Device helper routines are invoked by setting required register values, 
placing the device helper function code in DL, and executing: 

CALL DWORD PTR [DevHlp] 


5.2 Initialize Time Helper Routines 

Initialize time helper services perform interrupt management, memory 
management, timer management, character monitor management, sys¬ 
tem services and inter-device driver initialization functions. 

5.2.1 Interrupt Management Helper Services 

The initialize routine typically sets hardware interrupt (IRQ) entry points 
for use at a later time (say, in response to a READ strategy packet), and 
sets limits on stack usage by the interrupt service routine. The initialize 
routine, however, may need to perform certain I/O functions at the outset. 
The initialize routine is free to set and, if needed, to release the IRQ 
interrupt service routines it needs in order to perform initialization. The 
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interrupt service routine should not block while handling I/O, but should 
poll on a flag shared by the interrupt service routine. 

5.2.1.1 Alert System of Stack Requirements (RegisterStackUsage, 38h) 

The interrupt routine has several phases, each of which may require stack 
usage. If the interrupt routine is entered with interrupts disabled, the 
total stack usage can be only that of the interrupt routine. If the interrupt 
routine later enables interrupts (processor STI instruction), other inter¬ 
rupts can occur and the total of all interrupt stack usage must be 
computed. Finally, the interrupt routine may enable its IRQ level at the 
PIC, allowing nested interrupts. The stack demands of all possible nested 
routines must also be computed. 

USAGE: 

MOV BX, OFFSET StackUsage offset of stack usage struc- 

ture in main data segment 


MOV DL, 38h code for RegisterStack¬ 

Usage 

DS must contain device driver data segment 
value: 


CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR if carry is set, an error 

has occurred 

At this point, stack space has been allocated. 


ERROR: 
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AX contains the error code. The only error avail¬ 
able is "stack usage exceeds maximum." Device 
driver must deinstall itself. 


The StackUsage structure has the following format: 


StackUsage LABEL BYTE 


DW 14 

14 bytes in structure 

DW 1 

If bit 0=1, this interrupt 
routine enables interrupts. 
Set to 0 only if interrupt 
routine runs to completion 
without enabling inter¬ 
rupts. 

DW IRQnum 

Number of IRQ this driver 
will intercept. Issue 

Register StackUsage once 
for each IRQ this driver in¬ 
tercepts. 

DW nnl 

maximum number of bytes 
needed on stack while in¬ 
terrupts are disabled 

DW nn2 

maximum number of bytes 
needed by this interrupt 
level after interrupts are 
enabled 

DW nn3 

maximum number of bytes 
needed by this interrupt 
level for each nested 
routine 

DW nn4 

maximum number of 
nested interrupts 

While these numbers vary according to device driver design, standard 
OS/2 device driver design strategies limit the number of nested interrupts 
to 1. In general, minimizing stack usage in an interrupt routine is 


beneficial. 
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5.2.1.2 Intercept Hardware Interrupt (SetIRQ, lBh) 

Interrupt requests generated by device controllers are arbitrated by the 
interrupt controller. The interrupt controller prioritizes interrupt re¬ 
quests so only the highest priority request will be granted. Management 
of the interrupt controller occurs in a partially hardware-independent 
way using SetIRQ and EOI. 

In the AT and PS/2 machines, the interrupt controller is a cascaded 
master/slave interrupt controller arrangement. IRQ2 of the master 8259 
is activated by the slave 8259. Each of the master interrupt levels, 0-7, is 
associated with an interrupt vector in the range 50h-57h. Similarly, each 
of the slave interrupt levels 8-OFH is associated with an interrupt vector 
in the range 70h-77h. SetIRQ associates an interrupt level with an 
interrupt entry point that is within the device driver, relieving the driver 
writer of the responsibility to know about the association between IRQ 
level and interrupt vector. The driver writer needs to have knowledge only 
of the IRQ level. Some of the preassigned IRQ levels are shown in Table 
5-1: 


Table 5-1: Preassigned IRQ Levels 


8259 

IRQ 

DEVICE 

Master 

0 

Real-Time Clock (18 milliseconds), only in use in 
compatibility box. 


1 

Keyboard interrupt. 


2 

Slave 8259 request. 


3 

COM2 serial port. 


4 

COM1 serial port. 


5 

LPT2 parallel port. 


6 

Floppy disk. 


7 

LPT1 parallel port. 

Slave 

8 

Real-time clock (31.25 milliseconds), used for 
protect-mode scheduling. Received by com- 
patability box every .98 milliseconds. 


9 

EGA scan line 


OAh 

unused. 
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Table 5-1; Preassigned IRQ Levels 


8259 

IRQ 

DEVICE 

Slave 

OBh 

unused. 


OCh 

unused. 


ODh 

80287 Coprocessor. 


OEh 

Hard Disk. 


OFh 

unused. 


When the processor interrupt flag is set and allows interrupts, and 
when a hardware interrupt is requested by a device controller (and is the 
highest priority interrupt of all pending requests), interrupts are disabled 
and control is passed to the entry point of the device driver specified by 
the SetIRQ request. 

OS/2 supports shared interrupts r where several device driverssharea 
single interrupt level. A single driver in which the interrupt is arbitrated 
among several logical devices is not considered shared. In the case of 
shared interrupts, the interrupt entry of each device driver is called in 
turn. It is the responsibility of each device driver to determine if this 
interrupt is meant for this driver and to perform appropriate processing 
if so. The interrupt service routine indicates the interrupt has been 
serviced by clearing the carry bit before returning to the kernel. A shared 
interrupt is not available for exclusive use and an interrupt that has been 
assi gn ed exclusively to a driver cannot be used by any other driver. 
Interrupt service routines which share IRQs are entered with interrupts 
enabled. 

Shared interrupts require the interrupt controller to be level-triggered 
so that multiple simultaneous interrupt requests are not lost. This ar¬ 
chitecture is supported by the PS/2. The AT supports an edge-triggered 
interrupt controller. If two devices request interrupts on a shared line, 
the controller can only latch one, and "forgets" the second interrupt 
request. Consequently, AT interrupts may not be shared. 

Interrupts that are used to cascade the slave 8259 interrupt controller 
are not available for the device driver. IRQ2 is reserved for this use on 
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the AT and PS/2 machines. Interrupts received by the interrupt manager, 
and that have not been issued a SetIRQ, cause OS/2 to permanently 
disable that IRQ level at the PIC. 


USAGE: 


MOV AX,IRQoffset 

offset in code segment of 
interrupt entry point 

MOV BX,IRQnum 

interrupt level (O-OFh) 

MOV DH,ShareFlag 

shared interrupt flag: 


0 = not shared 


1 = shared 

MOV DL,lBh 

code for SetIRQ 

DS must contain device driver data segment 
value. This value will be placed in DS before in¬ 
terrupt entry is called. 


CALL DWORD PTR [DevHlp] 

address of device helper in 
terface, extracted from 

Init I/ 0 packet 

JC ERROR 

if carry is set, an error oc¬ 
curred 


At this point, IRQ has been intercepted. 


ERROR: 

AX contains the error code. The only error avail¬ 
able is "IRQ is not Available." 


5.2.1.3 Clearing an IRQ Level of the PIC (EOI, 31 h) 

The EOI device helper routine issues an End-of-Interrupt to a 
master/slave 8259 interrupt controller. The interrupt level for which the 
EOI is issued, is now active and will generate an interrupt when re- 
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quested by a device controller. If the EOI is issued for an IRQ level and a 
device controller is requesting an interrupt, the interrupt will immedi¬ 
ately occur. If the interrupt originates from the requesting controller, a 
"nested" interrupt takes place. Nested interrupts cause increased stack 
usage, which must be carefully considered before the EOI is issued. 
Nested interrupts are postponed by clearing the interrupt flag and disa¬ 
bling all interrupts. The processor instruction CLI is used to clear this 
flag. 

The EOI service is normally issued from an interrupt service routine 
and is available to the initialization routine for use at termination of an 
interrupt handler. Normally, this division of responsibility is considered 
poor programming procedure and the interrupt routine would be given 
exclusive control over the EOI service. 

USAGE: 

MOV AL, IRQnum number of interrupt level 

to be cleared (O-OFh) 

MOV DL, 31h code for EOI 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 


JC ERROR 

Here the IRQ level has been intercepted by the 
driver. 

ERROR: 

Register AX contains the error code. Currently 
defined code is "IRQ level not available." 


5.2.1.4 Remove Interrupt Handler (UnSetIRQ, ICh) 

If a hardware interrupt (IRQ) is needed only at initialize time (this is an 
unu sual case), the initialize routine may issue SetIRQ for that IRQ level, 
program the device controller, wait in a loop for the interrupt service to 
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complete (the initialize routine cannot block), and then remove the 
interrupt handler. 

USAGE: 


MOV BX, IRQnura IRQ level (O-OFh) of inter- 

rupt to be removed 

MOV DL, ICh code for UnSetIRQ 

DS must contain device driver data segment 
value before this call. 


CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 


JC ERROR 

Here the interrupt routine has been removed. 
ERROR: 

Register AX contains the error code. Currently 
defined code is "IRQ level not owned by device 
driver." 


5.2.2 Memory Management Helper Routines 

Physical memory may be allocated by the initialization routine for use by 
the driver and, if not needed after initialize time, may be released. This 
memory must be mapped to a selector before use. Global selectors maybe 
permanently allocated at initialize time (only), or local selectors may be 
used to temporarily map physical memory. 

5.2.2.1 Allocating Memory (AllocPhys, 18h) 

A memory block of arbitrary size is allocated, and its physical address is 
made available to the device driver. This memory is fixed against swap 
or motion and therefore, its physical address will not change over the life 
of the driver. 
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Memory is allocated from either low (below 1M) or high address regions. 
An error is returned if insufficient room remains in the requested region 
and the driver may retry the allocation in the other region if appropriate. 
If an attempt to allocate memory from the high region is unsuccessful, a 
second attempt to allocate the memory from the low region may succeed. 

The physical address of the memory is retumed~to the driver. This 
address must be mapped to a segment/selector before it may be used. 

USAGE: 

MOV AX,highsize 
MOV BX,lowsize 
MOV DL,18h 

CALL DWORD PTR [DevHlp] 


JC ERROR 

AX now contains high order 16 bits of address of 
start of allocated memory. 

BX now contains low order 16 bits of address of 
end of allocated memory. 

ERROR: 

AX contains the error code. The only possible 
error code is "Memory not Allocated." 


high order 16 hits of 
desired memory size 

low order 16 hits of 
desired memory size 

code for AllocPhys 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 

if carry set, error in alloca¬ 
tion 


5.2.2.2 Deallocating Memory (FreePhys, 19h) 

Memory previously allocated by AllocPhys is deallocated by FreePhys. 
This memory must be released if the device driver deinstalls. 

Only memory previously allocated by AllocPhys may be deallocated by 
FreePhys. 
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USAGE: 


MOV AX,highaddr 

MOV BX,lowaddr 

MOV DL,19h 


high order 16 bits of ad¬ 
dress of start of allocated 
memory 

low order 16 bits of ad¬ 
dress of start of allocated 
memory 

code for FreePhys 


CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init HO packet 

JC ERROR if carry is set, error in 

deallocation 

Memory has been successfully deallocated. ^ 

ERROR: 


AX contains the error code. The only possible 
error code is "Cannot free memory that was not 
previously allocated with AllocPhys." 


5.2.2.3 Allocating Global Selectors (AllocGDTSelector, 2Dh) 

A set of global selectors may be allocated from the pool of available 
selectors for use throughout the life of the device driver. A maximum of 
8,192 selectors is available for use of the entire system. The allocated 
selectors are now available for mapping by the driver. Only locked 
memory may be so mapped (such as that allocated by AllocPhys). These 
selectors will not be accessible by tasks, as tasks may access only local 
descriptors. Allocated global selectors should not be passed to device 
helper routines. 

Use of global selectors is recommended if a large number of segments 
is to be mapped, if memory segments are to be mapped permanently, or 
if memory segments are to be communicated between drivers. Temporary 
mapping of a small number of segments may be accomplished by other 
means. 
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USAGE: 


MOV AX,SEG GDTarray 
MOV ES,AX 

MOV DI, OFFSET GDTarray List of GDT selectors will 

be placed in GDTarray. 
Note that if GDTarray is 
in main data segment, 
load ES from DS since DS 
address is not bi-modal. 

MOV CX, count number of descriptors to 

be allocated 

MOV DL, 2Dh code for AliocGDTSelector 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR if carry is set, error in al¬ 

location of segments 

List of "count" selectors had been placed in 
"GDTarray." These selectors are invalid for use 
until memory is mapped to them with 
PhysToGDTSelector. 

ERROR: 

Error code is in AX. Only defined error is "Insuffi¬ 
cient selectors available." 

In some data segment: 

GDTarray DW count rep (?) 


5.2.2.4 Mapping Memory to Global Selector (PhysToGDTSelector, 2Eh) 

Physical memory addresses allocated by AllocPhys must be mapped to a 
selector before use by the driver. Once mapped, the global selector 
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remains valid for the life of the system, or until remapped by 
PhysToGDTSelector. 

Once mapped, the global selectors may be used by any driver, but may 
not be passed to device helper routines. Global selectors cannot be ac¬ 
cessed from a task. 

USAGE: 


MOV 

AX,highaddr 

high order 16 bits of ad¬ 
dress of start of allocated 
memory 

MOV 

BX,lowaddr 

low order 16 bits of ad¬ 
dress of start of allocated 
memory 

MOV 

CX,size 

size of segment to be 
mapped. A maximum of 
64K bytes may be mapped 
by a single selector. Value 

0 means 64K bytes 
(65,536). 

MOV 

SI,selector 

place selector value is SI 
(from array of selectors al¬ 
located by 

Alio cGDTSelector) 

MOV 

DL,2Eh 

code for 

PhysToGDTSelector 

CALL 

DWORD PTR [DevHlp] 

actdress of device helper in¬ 
terface, extracted from 

Init I/O packet 

JC 

ERROR 

if carry is set, error in 
mapping of memory 


Now locked physical memory is mapped to selec¬ 
tor. 

ERROR: 

Now AX*contains the error code. The only defined 
error code is "invalid physical address." 



214 WRITING OS/2 DEVICE DRIVERS 


5.2.2.S Allocate and Map Local Selector (PhysToUVirt, 17h) 

Physical memory addresses allocated by AllocPhys must be mapped to a 
selector and offset before use by the driver. This device helper routine 
converts a physical address to an address usable by the initializ e routine. 

PhysToUVirt allocates a local selector in the task address space and 
maps the physical memory to the selector. In initialize mode, the selector 
is allocated in the initialize thread and therefore, is not accessible to other 


tasks. The allocated selectors must be released before returning from the 
initialize thread. 

USAGE: 

MOV AX,highaddr 

high order 16 bits of ad¬ 
dress of start of allocated 
memory to be mapped 

MOV BX,lowaddr 

low order 16 bits of ad¬ 
dress of start of allocated 
memory to be mapped 

MOV CX,length 

Desired length of segment. 
Since segment lengths are 
limited to 64K, a single 
large memory allocation 
may require several seg¬ 
ments to map it in its en¬ 
tirety. Value 0 means 
maximum segment size of 
64K (65,536). 

MOV DH,1 

Value 1 means make seg¬ 
ment read / write segment. 
Value 0 is also available, 
meaning make read-only 
segment. This option 
would have little use in in¬ 
itialize context. 

MOV DL,17h 

code for PhysToUVirt 


CALL DWORD PTR [DevHlp] 


address of device helper in¬ 
terface, extracted from 
Init I/O packet 
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JC ERROR 

Here ES contains allocated selector, and BX the 
offset to the mapped address. Memory is mapped 
in protect mode with an offset of BX=0. 

ERROR: 

Here AX contains the error code. The only 
defined error is "invalid address." 


5.2.2.6 Release Local Selector (PhysToUVirt, 17h) 

Before returning from the initialize function, all local selectors allocated 
with PhysToUVirt must be released. Selectors are released one at a time 
and one release must eventually follow each allocation. 


USAGE: 


MOV AX,selector 

place selector to be 
released in AX 

MOV DH,2 

code to release selector 

MOV DL,17h 

code for PhysToUVirt 

CALL DWORD PTR [DevHlp] 

address of device helper in¬ 
terface , extracted from 

Init I/O packet 

JC ERROR 


Here selector has been released. 



ERROR: 

Error code is placed in AX. Only defined code is 
"invalid selector." 
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S.2.2.7 Temporary Mode-Independent Map (PhysToVirt, 15h) 

Physical memory addresses allocated by AllocPhys must be mapped to a 
selector before they are used by the driver. This device helper routine 
converts a physical address to an address that is usable by the initialize 
routine. 

PhysToVirt allows mapping of only two addresses, one to DS:SI and one 
to ES:DI (SI and DI are set to 0 by the mapping process). Two global 
selectors are reserved by the operating system for the initialization 
context for protect-mode mapping. One selector is specifically reserved 
for each selector register (DS and ES). Remapping a single selector 
register causes a remap of the underlying global descriptor. If a mapping 
is made and the pointer is stored for future access, care must be taken 
not to cause remapping of the implied global selector—this would in¬ 
validate the stored pointer. 

DOS (real-mode) device drivers allow mapping of physical memory to 
the segment:offset pairs DS:SI or ES:DI. If the physical memory addres¬ 
ses to be mapped are below 1M, no further problems arise. Mapping 
memory above 1M in DOS mode, however, may result in serious complica¬ 
tions. 

On a 80386 processor, mapping an address above 1M results in switch¬ 
ing the processor from real to protect mode. If either register ES or DS 
contains the address of the main data segment, its contents will be 
converted to the selector value for the main data segment. All stored real¬ 
mode pointers are invalidated, as is any segment register value not in the 
main data segment. 

On the 80286 processor, mapping an address above 1M causes the 
undocumented processor instruction LOADALL to establish the contents 
of shadow registers, enabling access of high memory from real mode. The 
segment register cannot be saved or altered in this state, and the inter¬ 
rupt flag is cleared preventing use of the segment register from another 
context. DevHlp routines cannot be called while this mapping is current. 

USAGE: 


MOV BP,SP 


prepare to call DevHlp in 
unknown context 
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PUSH WORD PTR DevHlp+2 save helper entry point 

PUSH WORD PTR DevHlp 

MOV AX, highaddr high order 16 bits of ad- 

dress of start of allocated 
memory to be mapped 

MOV BX, lowaddr low order 16 bits of ad¬ 

dress of start of allocated 
memory to be mapped 

MOV CX, length Desired length of segment. 

Since segment lengths are 
limited to 64K, a single 
large memory allocation 
may require several seg¬ 
ments to map it in its en¬ 
tirety. Value 0 means 
maximum segment size of 
64K (65,536). 

MOV DH,ResultCode ResultCode determines 

where returned seg¬ 
ment I off set pointer will be 
placed. This code serves to 
select which of the two 
global selectors will be 
used. 

0 = return pointer in DS:SI. 

1 = return pointer in ES:DI. 

MOV DL, 15h code for PhysToVirt 

Register DS must contain the address of the 

main data segment before the first call to PhysTo¬ 
Virt. 

CALL DWORD PTR [BP-4] address of device helper in¬ 

terface, extracted from 
Init HO packet 

JC ERROR if carry is set, error in map 

Now returned segment/selector and offset pointer 

to mapped memory is located in DS:SI or ES:DI. 
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JZ MODECHANGE 

No mode change has taken place, so all stored ad¬ 
dresses remain valid. 

MODECHANGE: 

Mode was changed from real mode to protect 
mode. Any real-mode stored pointers, or pre¬ 
viously mapped pointer in other segment 
register, are invalid and must be remapped. This 
condition can only take place in real mode device 
drivers. 

ERROR: 

Now AX contains the error code. The only pos¬ 
sible error code is "Invalid Address." 


5.2.2.8 Terminate Mode-Independent Map (UnPhysToVirt, 32h) 

Only one call to UnPhysToVirt is made to release the mapping context— 
even if many calls to PhysToVirt were made (note that only two addresses 
are simultaneously valid). 

UnPhysToVirt must be called before returning from the initialization 
routine. If UnPhysToVirt is called in the protect mode context created by 
mapping an address above 1M on a 80386 processor, the context is 
returned to real mode. Register DS is set to the value it had before the 
first PhysToVirt call, and register ES is not preserved. 


USAGE: 


MOV DH,32h 

code for UnPhysToVirt 

CALL DWORD PTR [BP-4] 

address of device helper in¬ 
terface, extracted from 

Init I/O packet 

MOV SP,BP 

Both selectors have now been released. 

restore stack pointer 
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JZ MODECHANGE 

No mode change has taken place, so all stored ad¬ 
dresses remain valid. 

MODECHANGE 

Mode was restored to real mode. This condition 
can only take place in real mode device drivers. 
DS is restored to point to the main data segment, 
contents of ES are undefined. 


5.2.2.9 Lock Device Driver Segments (Lock, 13h) 

Device driver segments in high memory (segments other than the main 
data and code segments) can be locked permanently with this lock. No 
lock handle will be returned, as driver segments will be irreversibly 
locked. 


USAGE: 

MOV AX,Selector 

MOV BH,3 
MOV BL,1 

MOV DL,13h 

CALL DWORD PTR [DevHlp] 

JC ERROR 


place the selector address 
of the device driver seg¬ 
ment to be locked into AX. 

code for permanent lock of 
device driver segments. 

1 = Do not block. The in¬ 
itialization routine is 
prohibited from blocking. 

code for DevHlp service 
Lock 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 

if carry is set, selector was 
invalid 


The device driver segment has been permanently 
locked into memory. 
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ERROR: 

Selector was invalid. Registers AX and BX are 
not preserved. 


5.2.3 Timer Management at Initialize Time 

A timer entry point may be established by the initialize routine, which 
will immediately receive timer interrupts. This timer entry point may be 
used by the initialize routine for polling or time-out purposes. 

5.2.3.1 Register Single-Tick Timer Handler (SetTimer, lDh) 

Establish an offset into the device driver code segment to be called at each 
clock tick. Entry will be made in protect mode with interrupts enabled, 
and must be dismissed with a far return instruction (RETF). All registers 
must be preserved. 

Any processing overhead in the timer routine is added to system 
overhead for each clock tick, reducing processor availability for all user 
processes. Extreme timer overhead will result in lost clock ticks. For these 
reasons, the timer code must be extremely efficient. 

USAGE: 

MOV AX, TimerOf f set offset of timer entry point 

in code segment 

MOV DL, lDh code for SetTimer 

The DS register must contain the device driver 
data segment selector. If DS has been changed 
for any reason, restore before this call. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init 110 packet 


JC ERROR 


error took place 
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At this point, the timer entry point has been 
added to the list of entry points to be called each 
clock tick. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Timer Handler Disallowed." This 
error arises if: 

—System maximum number of timer entry 
points (32) is exceeded. 

—Timer entry point is already in use 

5.2.3.2 Register n-Tick Timer Handler (TickCount, 33h) 

If called with a previously registered timer entry point, the timer tick 
count is modified so the timer routine is called every n tick counts. If called 
with an unregistered timer entry point, TickCount establishes an offset 
into the device driver code segment to be called every n clock ticks. 

Entry to the timer routine will be made in protect mode with interrupts 
enabled and must be terminated with a FAR, return instruction. 

Any processing overhead in the timer routine is added to system 
overhead every n clock ticks. While the impact of this overhead is much 
less than that of SetTimer (which enters the clock routine every tick), the 
reduction of processor availability for all user processes must be con¬ 
sidered. Extreme timer overhead will result in lost clock ticks. For these 
reasons, the timer code must be extremely efficient. 

The number of ticks between calls to the timer entry point, n, may be 
any number from 1 to 65,535. Value n=0 represents 65,536 ticks. 


USAGE: 


MOV AX,TimerOffset 

offset of timer entry point 
in code segment 

MOV BX, n 

Set BX to the tick count 
desired between calls to 
the timer entry point. n=0 
means 65,536 ticks . 

MOV DL,33h 

Code for TickCount 
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The DS register must contain the device driver 
data segment selector. If DS has been changed 
for any reason, restore before this call. 

CALL DWORD PTR [DevHlp] 


JC ERROR 

At this point, the timer entry point has been 
added to the list of entry points to be called each 
clock tick. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Timer Handler Cannot be Set or 
Modified." This error arises for a new timer entry 
point if: 

—System maximum number of timer entry 
points is exceeded. 

—Timer entry point is already in use. 

5.2.3.3 Remove Timer Handler (ResetTimer, lEh) 

After a timer handler has been utilized by the initialization routine, it is 
removed. A later strategy routine may re-establish the timer handler. 
Alternatively, the timer handler may continue running and perform no 
operations until it is needed for later processing. This technique has the 
disadvantage of unnecessarily increasing timer overhead and impacting 
system performance. 

USAGE: 

MOV AX, TimerOf f set offset of timer entry point 

in main code segment 

MOV DL,lEh 

The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 


address of device helper in¬ 
terface , extracted from 
Init 110 packet 

error took place 


code for ResetTimer 
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CALL DWORD PTR [DevHlp] address of device helper in- 

ter face, extracted from 
Init I/ O packet 

JC ERROR error took place 

At this point, this timer handler has been 
removed from the list of handlers to be called at 
timer interrupt time. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Timer Handler not in Use." 


5.2.4 Character Monitor Initialization 

At initialize time, a character monitor chain may be created for later use. 
Since OS/2 is single-threaded at initialize time, neither monitor threads 
nor the monitor dispatcher are running, and characters may not be 
written to the chain. 

5.2.4.1 Creating a Monitor Chain (MonitorCreate, lFh) 

This function creates an empty chain of monitors and associates the chain 
with a fin al buffer and notification routine. A process opens a connection 
with a device monitor chain by means of the API call DosMonOpen which 
is formatted by the file manager into an OPEN request packet and passed 
to the device driver strategy routine. The MON bit of the status word in 
the packet is sent to indicate this as a monitor OPEN packet. 

A process places a monitor thread on the monitor chain by means of the 
API call DosMonReg, which is translated into the Register Monitor IOCtl 
(category OAh, function 40h). The device driver strategy routine registers 
the monitor thread to a driver-selector chain by means of the Register 
DevHlp call. Each monitor registered to the chain is now on fine to process 
data sent through the chain. 

The strategy or interrupt routines write a character to the monitor 
nhain. If the chain is empty, the character is written to the final buffer 
and the notification routine is called in the context of the driver routine 
that wrote the character (which may be strategy or interrupt context). 
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Otherwise, the first monitor in the chain is activated in its process 
context. When it runs, it reads data from the chain, and processes the 
character. The monitor thread then writes the processed character back 
to the chain, causing activation of the next monitor in the chain. When 
the last monitor writes back its character, the final buffer is filled with 
the processed character, and the notification routine is called in the 
context of the monitor dispatcher thread (ring 0). 


USAGE: 


MOV AX,DS 

the main data segment 
selector must be in ES 

MOV ES,AX 

MOV SI,OFFSET FinalBuffer 

The segment'.offset ad¬ 
dress of the final buffer is 
in ES:SI (note the unusual 
use of register pair). The 
final buffer must be in the 
main data segment. 

MOV AX,CS 

the main code segment 
selector must be in CS 

MOV DI,Notify 

The segment'.offset ad¬ 
dress of the notification 
routine is in DS.DI (note 
the unusual use of register 
pair). The notification 
routine must be in the 
main code segment. 

MOV AX,0 

O-Create Monitor 

MOV DL,IFh 

code for MonitorCreate 

CALL DWORD PTR ES:[DevHlp] 

address of device helper in¬ 
terface , extracted from 

Init I/O packet 

JC ERROR 


AX is the handle for the monitor chain. This 
value must be used to register monitors in 



response to the Register Monitor IOCtl. 

ERROR: 

The error code is placed in AX. The only defined 
error code is "Invalid Monitor Handle." 
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5.2.5 Getting OS/2 Internal Variables at Initialize Time 

Certain OS/2 variables are available at initialize time. The global infor¬ 
mation segment contains time, date, and other information, and the COM 
port words are used to establish ownership of COM ports COM1 and 
COM2. The other variables are invalid or not of interest at initialize time. 

5.2.5.1 Return Pointer to DOS Variable (GetDosVar, 24h) 

Each OS/2 internal variable is associated with a unique and bi-modal 
address. This address is returned with GetDosVar for a particular vari¬ 
able. The address may then be used in the initialization mode, or in any 
other mode within the device driver. Note that not all variables have valid 
values at interrupt time. Only the global INFO segment, the COM port 
words, and the reboot vector are valid at interrupt time. Table 5-2 lists 
the variable codes. 


Table 5-2; Available Variable Codes __ 

CODE DESCRIPTION 

1 Address of a word containing the bi-modal segment address of the global 
INFO segment. The global INFO segment contains the current date and 
time, the current screen group, and other miscellaneous data. The global 
INFO segment is described further in the appendices. 

2 Address of the offset, segment address of the local INFO segment. The 
local segment contains the screen group number, process ID, and thread 
ID of the initialize process. This information generally is not useful to 
the device driver at initialize time. 

3 Address of the two COM ownership words. The first word contains the 
port numb er for COM1, and the second word contains the port number 
for COM2. The Value 0 means the port is owned by some device driver. 

5 Address of the offset, segment address of the OS/2 reboot vector. A JMP 

to this address will cause cold reboot of the operating system 

7 Address of the 1-byte Time Critical Yield flag. The Yield flag is not valid 
at initialize time. 

8 Address of the 1 -byte Time Critical Yield flag. The Time Critical Yield 
flag is not valid at initialize time. 
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USAGE 

MOV AL, VarCode Place the variable code of 

the variable whose ad¬ 
dress is required in AL. 

The variable code is 
drawn from the above 
table. 

MOV DL,24h Code for DosGetVar. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface , extracted from 
Init I/O packet 


JC ERROR 

The address of the variable is returned in AX:BX, 
AX containing the segment/selector, and BX con¬ 
taining the offset. 

ERROR: 

Variable code does not correspond to an OS/2 vari¬ 
able. 


5.2.6 Communicating Between Device Drivers 

A link may be established between an initializing device driver and a 
previously loaded character device driver. The previously loaded device 
driver is addressed by an eight-character name, and must have the IDC 
bit set in its driver header. The AttachDD DevHlp call will return the IDC 
entry point and main data segment address for the previously loaded 
driver. These values are returned for both real and protect mode. 

To utilize the IDC entiy point, the initializing driver determines if it is 
functioning in real or protect mode, sets registers accordingly, and calls 
the previously loaded driver with a FAR CALL. The previously loaded 
driver is responsible for interpretation and/or saving of registers, and 
terminating with a far return. 
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USAGE: 


MOV BX, DDnameOf f set Offset in current main 

data segment of 8-charac- 
ter blank-filled name of 
previously loaded charac¬ 
ter device driver 


MOV DI, IDCOffset offset in current main 

data segment of IDC data 

MOV DL, 2Ah code for AttachDD 

The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 


JC ERROR 


error took place 


At this point, the IDC data structure in the main 
data segment has been filled in, and can be used 
to call the IDC entry of the other device driver. 


ERROR: 

AX contains the error code. The only defined 
error code is "Device driver not found or does not 
support IDC." 

The format of the IDC data structure is depicted in Table 5-3. 


Table 5-3: IDC Data Structure 


OFFSET 

LENGTH 

DESCRIPTION 

0 

WORD 

Offset of IDC entry point. 

2 

WORD 

Real-mode CS of IDC driver. 

4 

WORD 

Real-mode DS of IDC driver. 

6 

WORD 

Offset of IDC entry point. 

8 

WORD 

Protect-mode CS of IDC driver. 

OAh 

WORD 

Protect-mode DS of IDC driver. 
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5.3 Device Helper Routines at Strategy Time 

All device helper routines are available to the strategy routine, with 
exception of the initialization time services, RegisterStackUsage and 
AllocGDTSelector,- and the interrupt time service EOI. 

5.3.1 Process Management Helper Services 

The strategy routine will typically perform one of three actions—imme¬ 
diately satisfy an information request, start an I/O request, or queue an 
I/O packet for later service if another I/O request is pending. 

If the request is informational in nature and capable of immediate 
service, the driver satisfies the request, sets the DONE bit in the request 
packet, and returns. 

If the strategy packet cannot be immediately serviced, the strategy 
routine must block until such service can be completed. The strategy 
routine may issue the Block service, and will be restarted by the Run 
service; or it may return without setting the DONE bit in the STATUS 
word of the strategy packet, and will be completed with the DevDone 
service. 

If the strategy routine is to perform extensive computations, it should 
check the Yield flag (or TCYield flag) to determine if a higher-priority 
thread is waiting for execution. Since the strategy routine cannot be 
interrupted by a higher-priority thread, it must yield to higher-priority 
threads using the services Yield or TCYield. 

If the strategy routine is entered in real mode, the driver may switch 
to protect mode. The driver is then required to return to real mode (and 
pay a 3 millisecond penalty) before blocking or returning to the kernel. 

5.3.1.1 Block Strategy Routine to be Awakened Later (Block, 4) 

If the strategy routine cannot immediately service a request, it must 
suspend for later completion. The strategy routine issues a Block service 
with a (hopefully) unique 32-bit value, which will be used later by an 
interrupt or strategy routine to unblock the strategy routine. 

Before a strategy routine blocks, it will typically check a condition, such 
as I/O queue not empty. This condition is often reset by the interrupt 
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service routine and therefore, the strategy routine will disable interrupts 
before checking the condition. When the strategy routine resumes after 
a block, the interrupts have been reenabled. Since the routine may have 
been inadvertently awakened by a duplicate 32-bit value in the Run 
routine, the strategy routine should again disable interrupts and check 
the blocking condition to determine if it should once again block. 

The strategy routine will resume when a Run service is issued with the 
32-bit value on which the block was issued. A 32-bit time-out interval may 
be specified, after this time period the strategy routine will also resume. 

Block may be interrupted by process death. The driver will then return 
the strategy packet with error code. The strategy routine will normally 
use the virtual address of the request packet as the 32-bit value on which 
to block. 


USAGE: 


MOV 

BX,LowWord 

LowWord is the low order 
word of the 32-bit value 
on which to block 

MOV 

AX,HighWord 

HighWord is the high 
order word of the 32-bit 
value on which to block 

MOV 

CX,LowTime 

LowTime is the low order 
word of the 32-bit time-out 
interval in milliseconds 

MOV 

DI,HighTime 

HighTime is the high 
order word of the 32-bit 
time-out interval in mil¬ 
liseconds 

MOV 

DH,InterruptFlag 

the driver specifies 
whether the block should 
be interrupted by process 
death 

0 = interrupt in case of 
process death 

1 = do not interrupt in 
case of process death 
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MOV DL, 4 code for Block 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC UNUSUAL if C set, time-out or 

process death 

At this point, Block was awakened by Run with 
same 32-bit value. If this value was not unique, 
the blocking condition must be checked to deter¬ 
mine if this routine was the one intended to be ac¬ 
tivated. Note that interrupts have been enabled 
at this point, and should be disabled if an inter¬ 
rupt-sensitive condition is to be checked. 

UNUSUAL: 


JNZ DEATH 

Here Block was awakened by time-out period 
lapsing. 

DEATH: 

Here Block was awakened by calling process 
death. Error code 11 h, I/O call interrupted, 
should be returned in the strategy packet. 

5.3.1.2 Resume Previously Blocked Strategy Routine (Run, 5) 

The Run service unblocks all strategy routines that are blocked on the 
same 32-bit value. While every effort is made by the driver writer to 
ensure uniqueness of the 32-bit value, the possibility of an erroneous 
awakening should be considered in coding the Block service. 

USAGE: 


AX contains the awake 
code . The only defined 
value is "Unusual Wake- 
Up." 

process death occurred 


MOV BX,LowWord 
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MOV AX, HighWord 

MOV DL,5 

CALL DWORD PTR [DevHlp] 

JZ NONEWAITING 


Low Word is the low order 
word of the 32-bit value 
on jwhich the block was is¬ 
sued 

HighWord is the high 
order word of the 32-bit 
value on which the block 
was issued 

code for Run service 

address of device helper in¬ 
terface , extracted from 
Init HO packet 

no Blocks were waiting 
with this 32-bit identifier 


AX contains the count of those strategy routines 
that were waiting on this identifier. 

NONEWAITING: 

No strategy routines were waiting on this 32-bit 
identifier. 


5.3.1.3 Flag I/O Completion in Kernel (DevDone, 1) 

A strategy routine may return without having set the DONE bit of the 
STATUS word of the strategy packet, in which event the packet is blocked 
by the kernel on the tiled address of the packet (contained in ES:BX). In 
this case the routine which will awaken the strategy routine will set the 
error status, and then issue the DevDone service with ES:BX containing 
the strategy packet address. The kernel sets the DONE bit and unblocks 
the strategy routine, which returns to the calling thread. 

USAGE: 

LES BX, request Place tiled address of 

strategy packet in ES:BX . 
The DONE bit of this pack¬ 
et will be set, and the 
strategy routine cor¬ 
responding to this packet 
will run to completion . 
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MOV DL, 1 code for DevDone 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 


5.3.1.4 Yield to Priority Threads (Yield, 2) 

Once a strategy routine starts and until it blocks, no other thread will be 
scheduled (interrupt routines will be executed). If a strategy routine 
executes computationally complex code (over 3 milliseconds), it should 
check to see if any higher-priority threads are waiting to execute. If a 
higher-priority thread is waiting, the strategy routine can give the 
priority thread a time-slice by invoking the Yield service. 

If the Yield service is used, the TCYield service need not be called. 

USAGE: 

MOV DL, 2 code for Yield service 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 


5.3.1.5 Yield to Time-Critical Threads (TCYield, 3) 

Once a strategy routine starts, and until it blocks, no other thread will be 
scheduled (interrupt routines will be executed). If a strategy routine 
executes computationally complex code (over 3 milliseconds), it should 
check to see if any time-critical threads are waiting to execute. If a 
time-critical thread is waiting, the strategy routine can give the time- 
critical thread a time-slice by invoking the TCYield service. 

If the Yield service is used, the TCYield service need not be called. 

USAGE: 


MOV DL,3 


code for TCYield service 
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CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
, Init I/ O packet 


5.3.1.6 Switch from Real Mode to Protect Mode (RealToProt, 2Fh) 

If the strategy routine is called from the compatibility box, the driver may 
switch from real mode to protect mode. The driver must return to real 
mode before blocking or returning to the kernel by use of DevHlp service, 
ProtToReal. This feature is of limited utility on 80286 machines as it takes 
about 3 milliseconds to complete the required switch from protect mode 
back to real mode. 

USAGE: 


MOV DL, 2Fh code for RealToProt 

DS must contain the real mode segment value for 
the main data segment. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR error took place 

At this point, processor mode has been switched 
from real to protect mode. All real-mode stored 
pointers are invalid. The contents of DS have 
been changed for protect-mode operation, and if 
ES contained the segment value for the real¬ 
mode data segment, its value is also changed to 
the corresponding protect-mode value. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Mode has not been Changed." 
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5.3.1.7 Return to Real Mode from Protect Mode (ProtToReal, 30h) 

If the driver is executing in protect mode as a result of using the DevHlp 
service, RealToProt, the driver must return to real-mode context before 
blocking or returning to the kernel. On 80286 machines it takes about 3 
milliseconds to complete the required switch from protect mode back to 
real mode. 

USAGE: 


MOV DL, 3 Oh code for RealToProt 

DS must contain the protect-mode segment value 
for the main data segment. 


CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR error took place 

At this point, processor mode has been returned 
to real mode from protect mode. All protect-mode 
stored pointers are invalid. The contents of DS 
have been changed for real-mode operation, and 
if ES contained the selector value for the protect¬ 
mode data segment, its value is also changed to 
the corresponding real mode value. 


ERROR: 


Now AX contains the error code. The only defined 
error code is "Mode has not been Changed." 


5.3.2 Memory Management Services at Strategy Time 

All memory management services are available, with the exception of 
AllocGDTSelector, which is only available at initialize time. 

Physical memory is allocated with AllocPhys, and released with Free- 
Phys. Physical memory may be mapped to global selectors with 
PhysToGDTSelector and to local selectors with PhysToUVirt. 
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The real/protect-independent mapping of physical memory to virtual 
memory is accomplished with PhysToVirt and undone with UnPhysTo- 
Virt. This mapping is most often used in interrupt mode where the context 
may vary, but is available for use in strategy context. PhysToVirt creates 
a context in which the driver may neither block nor use DevHlp services, 
and in which the selector registers may not be saved for future use. 

PhysToGDTSelector and PhysToUVirt are often preferred because of 
their more general application. 

Accessibility of virtual memory addresses is determined with Verify- 
Access. Virtual addresses are locked in memory with Lock, converted to 
physical addresses with VirtToPhys, and unlocked with Unlock. 

5.3.2.1 Allocate Physical Memory (AllocPhys, 18h) 

Physical memory can be allocated for use by the driver. This memory is 
locked, and its returned 24-bit address cannot be changed or unlocked. 
The 24-bit address cannot be directly used by the 80286 processor and 
must be mapped to a local or global selector before use. Either low memory 
in the first 1M of address space (which can be addressed in real mode), or 
high memory above the 1M address line can be allocated. 

USAGE: 

MOV AX, HighSize high order 16-bits of re- 

quested allocation size. Al¬ 
though only 64K bytes can 
be mapped by a single 
selector, the size of a 
single physical memory al¬ 
location may be as large 
as required. 

low order 16-bits of re¬ 
quested allocation size 

This flag indicates 
whether memory is to be 
allocated from low or high 
memory. 

0 = Allocate physical 
memory above 1M 


MOV BX,LowSiz e 
MOV DH,lowmem_flag 
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1 = Allocate physical 
memory below 1M 

MOV DL,18h code for AllocPhys 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR Error took place 

At this point, physical memory has been allo¬ 
cated and is available for mapping. The address 
of physical start of allocated memory is contained 
in AX, BX: 

AX = high order 16-bits of physical start of allo¬ 
cated memory. 

BX = low order 16-bits of physical start of allo¬ 
cated memory. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Memory not Allocated." 


5.3.2.2 Release Physical Memory (FreePhys, 19h) 

Physical memory previously allocated by AllocPhys can be released with 
FreePhys. Other physical memory addresses cannot be released with this 
call. 

USAGE: 

MOV AX,HighStart high order 16-bits of start¬ 

ing address of physical 
memory previously allo¬ 
cated by AllocPhys . This 
value was returned in AX 
by AllocPhys. 

MOV BX,LowStart Low order 16-bits of start¬ 

ing address of physical 
memory previously allo¬ 
cated by AllocPhys . This 
value was returned in BX 
by AllocPhys . 
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MOV DL,19h code for FreePhys 

CALL DWORD PTR [DevHlp] 


JC ERROR 

At this point, the physical memory whose start 
address was contained in AX, BX has been deallo¬ 
cated. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Cannot Free Memory not Pre¬ 
viously Allocated by AllocPhys." 

5.3.2.3 Map to Global Selector (PhysToGDTSelector, 2Eh) 

A global selector allocated at initialize time by AllocGDTSelector is not 
valid for use until a segment of physical memory has been mapped to it. 
Similarly, a segment of physical memory cannot be addressed unless 
mapped to a selector or segment. Once mapped to a global selector, the 
segment of memory can be addressed in protect mode in any context, 
whether interrupt, strategy, or other context. These selectors cannot be 
used by ring 3 threads, and should not be passed to DevHlp services. 

USAGE: 

MOV SI, GDTSelector global selector from list al¬ 

located by 

AllocGDTSelector is 
placed in SI 

MOV AX,HighStart High order 16-bits of start¬ 

ing address of physical 
memory previously allo¬ 
cated by AllocPhys, or lock¬ 
ed and converted from 
virtual to physical ad¬ 
dress. 


address of device helper in¬ 
terface , extracted from 
Init I/O packet 

Error took place 


MOV BX,LowStart 
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MOV CX,Length 

MOV DL,2Eh 

CALL DWORD PTR [DevHlp] 

JC ERROR 


Low order 16-bits of start¬ 
ing address of physical 
memory previously allo¬ 
cated by AllocPhys, or lock 
ed and converted from 
virtual to physical ad¬ 
dress . 

Length is the length of the 
segment of memory to be 
mapped . Value 0 repre¬ 
sents 64K bytes (65,536). 

code for 

PhysToGDTSelector 

address of device helper in 
ter face, extracted from 
Init I/O packet 

error took place 


At this point, the physical memory whose start 
address was contained in AX, EX has been 
mapped to the selector whose value is contained 
in SI. 


ERROR: 

Now AX contains the error code. The only defined 
error codes are "Invalid address" or "Invalid 
Selector." 


5.3.2.4 Map Physical Memory to Process-Local Selector 

If the strategy routine is executing in protect mode, a selector is allocated 
in the local address space of the underlying process, and a segment of 
physical memory is mapped to that selector (PhysToUVirt, 17h). This 
selector is valid for use within the process or strategy routine until the 
map is terminated. 

If the strategy routine is executing in real mode, a segment of physical 
memory is mapped to a segment:offset pair. Real-mode mappings need 
not be terminated, as no selector is allocated. 
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USAGE: 

MOV AX,HighStart 

MOV BX,LowStart 

MOV CX,Length 

MOV DH,WriteFlag 

MOV DL,17h 

CALL DWORD PTR [DevHlp] 

JC ERROR 


High order 16-bits of start¬ 
ing address of physical 
memory previously allo¬ 
cated by AllocPhys, or lock 
ed and converted from 
virtual to physical ad¬ 
dress. 

Low order 16-bits of start¬ 
ing address of physical 
memory previously allo¬ 
cated by AllocPhys, or lock 
ed and converted from 
virtual to physical ad¬ 
dress. 

Length is the length of the 
segment of memory to be 
mapped. Value 0 repre¬ 
sents 64K bytes (65,536). 

For protect-mode requests 
only, the WriteFlag indi¬ 
cates whether the mapping 
is to be read-only or 
read / write. 

0 = Read-only segment 

1 = Read / Write Segment 

code for PhysToUVirt 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 

error took place 


In protect mode, the selector value is returned in 
ES and the value 0 is returned in BX. In real 
mode, the segment register value is returned in 
ES and the offset value is returned in BX. In 
either mode, ES:BX now addresses the physical 
memory. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Invalid address." 
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5 . 3 . 2.5 Terminate Process-Local Map (PhysToUVirt, 17h) 

Protect-mode mappings to the local address space should be released 
when done, so the selector is returned to the local pool of available 
selectors. Real-mode mappings do not allocate selectors and are not 
terminated. 

USAGE: 


MOV 

AX,Selector 

Selector is the selector in 
the local address space, 
whose value was returned 
in ES by PhysToUVirt. 

MOV 

DH, 2 

code to release local selec¬ 
tor earlier allocated by 
PhysToUVirt 

MOV 

DL,17h 

code for PhysToUVirt 

CALL 

DWORD PTR [DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init I/O packet 

JC 

ERROR 

error took place 


At this point, selector in local address space has 
been released to the pool of available selectors for 
the process. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Invalid Selector." 


5.3.2.6 Temporary Mode-Independent Map (PhysToVirt, 15h) 

PhysToVirt is intended to provide a single means of mapping physical 
memory regardless of real/protect mode, specifically for performing string 
copy operations. The mapping is normally performed in pairs, and the 
results are stored in DS:SI and ES:DI. In general, the strategy routine 
may not save or restore these register pairs, call device helper routines, 
or block while the mapping is in effect. 
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For protect-mode operations, OS/2 reserves two global selectors for use 
by PhysToVirt. One is reserved for mapping physical memory to DS, and 
the other for mapping physical memory to ES. PhysToVirt maps a physical 
address to the selected GDT entry and places its selector in the selector 
register DS or ES. This selector can be stored, but will be remapped if the 
PhysToVirt is used to map the same selector register (DS or ES). This 
condition may be caused by another strategy routine if the strategy 
routine blocks. The offset register associated with the mapped selector 
register (DS:SI or ES:DI) is set to 0. 

For real-mode operations that map physical addresses below 1M, the 
segment:offset value is placed in DS:SI or ES:DI. These addresses may 
be stored for later use in real mode. 

The real-mode mapping of physical addresses in high memory on the 
80386 causes a context switch to protect mode operation. This invalidates 
previous real-mode mappings, and any real-mode segment values. If the 
main data segment address is contained in either DS or ES, the DS or ES 
value is converted to a selector value still pointing to the main data 
segment. The mapping must be terminated with UnPhysToVirt before the 
strategy routine can block. 

On the 80286, mapping of physical addresses in high memory causes 
the use of the undocumented processor LOADALL instruction, which 
loads shadow registers that enable addressing of high memory from real 
mode. The segment register is no longer valid and cannot be saved or 
restored. PhysToVirt disables interrupts to prevent inadvertent modifica¬ 
tion of this register. UnPhysToVirt must be called to terminate the 
mapping before interrupts are enabled (or the routine blocks). DevHlp 
services cannot be used while this mapping is in effect. 


USAGE: 


MOV BP,SP 

set up to call device helper 
routine without use of DS 


or ES 

PUSH WORD PTR DevHlp+2 

PUSH WORD PTR DevHlp 

MOV AX,highaddr 
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• 

high order 16 bits of ad¬ 
dress of start of physical 
memory to be mapped 

MOV 

BX,lowaddr 

low order 16 bits of ad¬ 
dress of start of physical 
memory to be mapped 

MOV 

CX,length 

Desired length of segment. 
Since segment lengths are 
limited to 64K, a single 
large memory allocation 
may require several seg¬ 
ments to map it in its en¬ 
tirety. Value 0 means 
maximum segment size of 
64K (65,536). 

MOV 

DH,ResultCode 

ResultCode determines 
where returned seg¬ 
ment /offset pointers will 
be placed. This code serves 
to select which of the two 
global selectors that will 
be used. 



0 = return pointer in 

DS:SI 

1 = return pointer in 

ES:DI 

MOV 

DL,15h 

code for PhysToVirt 

Register DS must point to the main data seg¬ 
ment before the first call to PhysToVirt. 


CALL 

DWORD PTR [BP-4] 

address of device helper in¬ 
terface, extracted from 

Init 110 packet 

JC 

ERROR 

if carry is set, error in 
mapping 


Now returned segment/selector and offset pointer 
to mapped memory is located in DS:SI or ES:DI 


JZ MODECHANGE 

No mode change has taken place, so all stored ad¬ 
dresses remain valid. 


MODECHANGE: 
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Mode was changed from real mode to protect 
mode. Any real mode stored pointers, or pre¬ 
viously mapped pointer in other segment 
register, are invalid and must be remapped. 

ERROR: 

Now AX contains the error code. The only pos¬ 
sible error code is "Invalid Address." 


d.3.2.7 Terminate Mode-Independent Map (UnPhysToVirt, 32h) 

Only one call to UnPhysToVirt is made to release the mapping context- 
even if many calls to PhysToVirt were made (note that only two addresses 
are simultaneously valid). 

UnPhysToVirt must be called before returning from the initialization 
routine. If UnPhysToVirt is called in the protect-mode context created by 
mapping an address above 1M on a 80386 processor, the context is 
returned to real mode. If UnPhysToVirt is called after mapping an address 
above 1M on a 80286 processor, the driver should then reset the interrupt 
flag to its value before the PhysToVirt call. DS is set to the main data 
selector. ES is not preserved. 

USAGE: 

MOV DH, 32h code for UnPhysToVirt 

CALL DWORD PTR [BP-4] address of device helper in¬ 

terface, extracted from 
Init 110 packet 

MOV SP,BP restore stack 

Both selectors have now been released. 

JZ MODECHANGE 

No mode change has taken place, so interrupt 

flag has not been altered. 

MODECHANGE: 

Mode was changed from real mode to protect 

mode. Interrupt Flag Should Be Restored. 
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5.3.2.8 Verify Virtual Memory Addressability in Process Context 

A virtual address may be received from an IOCtl strategy packet, and it 
should be verified by the device driver for addressability by the calling 
process (VerifyAccess, 27h). The driver should verify all the addresses it 
will use, then lock those addresses so the process cannot release or alter 
the memory. The driver should not block or yield between the VerifyAccess 
call and locking the memory. This prevents the process from possibly 
gaining control and releasing the memory. If VerifyAccess fails, the 
process is terminated—independent of driver action. 

USAGE: 


MOV 

AX,selector 

place segment /selector 
value of virtual memory in 
AX 

MOV 

DI,offset 

place offset of virtual 
memory address in DI 

MOV 

CX,length 

lace segment length of vir¬ 
tual memory region in CX 

MOV 

DH,WriteFlag 

writeFlag is 0 for read¬ 
only access, 1 for 
read / write access 

MOV 

DL,27h 

code for VerifyAccess 

CALL 

DWORD PTR [DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init I/ 0 packet 

JC 

ERROR 

if carry is set, virtual 
memory was not accessible 


Access to virtual memory by calling process has 
been verified. 


ERROR: 

Calling process did not have access rights to vir¬ 
tual memory. The calling process has entered a 
termination state. 
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5.3.2.9 Lock Virtual Memory Against Swap or Relocation (Lock, 13h) 

Virtual memory addresses passed by a process to the device driver in an 
IOCtl packet may be locked into memory, after which time its physical 
address may be used. If the virtual address is not present in physical 
memory, the driver may block until the memory has been read from the 
swapping device. If the driver blocks for this or any other reason, virtual 
addresses should be checked after the lock for addressability by the calling 
process with DevHlp call, VerifyAccess. 

Memory is divided into short-term and long-term locking store. Short¬ 
term storage locks virtual memory at its current physical address, and 
for performance and fragmentation reasons should not be maintained for 
more than two seconds. If a memory lock is to be maintained more than 
two seconds, a long-term lock should be specified, which will move the 
segment into long-term storage. After the virtual address has been locked, 
its physical address may be determined with DevHlp call, VirtToPhys. 

The Lock DevHlp service returns a lock handle, which is passed to 
the Unlock DevHlp service to unlock virtual memory—rendering it mov¬ 
able and swappable. This lock handle is a 32-bit integer distinct from the 
physical address of the memory and must be stored in order to later 
release the virtual memory lock. 


USAGE: 

MOV 

AX,selector 

MOV 

BH,Term 

MOV 

BL,BlockFlag 


MOV DL,13h 


selector of virtual address 
to be locked 

Short-term locks are 
specified with Term = 0. 
Long-term locks use Term 
= 1 . 

If BlockFlag is 1, do not 
block if virtual address is 
not in memory and must 
be read from swap store. 

If BlockFlag is 0, the 
strategy routine will block 
until the virtual address 
is locked. 

code for DevHlp service 
Lock 
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CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR If carry set, segment could 

not be locked. Segment 
may be present on swap 
store. 


AX, BX contains a 32-bit "lock handle" which is 
used to unlock this memory (DevHlp call, Un¬ 
lock). 

ERROR: 

Segment could not be locked, or the selector was 
invalid. Registers AX and BX are not preserved. 


5.3.2.10 Convert Virtual Address to Physical Address (VirtToPhys, 16h) 

The handle returned by DevHlp service Lock is not the physical address 
of the memory. After the Lock is issued, VirtToPhys is issued to convert 
the virtual address to a physical address. The physical address can now 
be mapped to a virtual address in any context (i.e., interrupt context). 


USAGE: 


MOV 

AX, DS 

preserve pointer to main 
data segment 

MOV 

ES, AX 


MOV 

DS,Selector 

place selector of virtual ad¬ 
dress in DS 

MOV 

SI,Offset 

place offset of virtual ad¬ 
dress in SI 

MOV 

DL,16h 

code for DevHlp service 
VirtToPhys 

CALL 

DWORD PTR ES:[DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init I/O packet 
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JC ERROR if carry is set, virtual ad¬ 

dress was invalid 

Physical address is contained in AX, BX. The 
high-order 16-hits of physical address are con¬ 
tained in AX, and the low-order 16-bits are 
placed in BX. 

ERROR: 

Virtual address was invalid. 


5.3.2.11 Unlock Virtual Memory (Unlock, 14h) 

Short-term and long-term memory locks are released with Unlock, which 
takes as, argument the 32-bit lock handle returned from DevHlp service, 
Lock. Permanent lock of device driver segments cannot be undone. 

USAGE: 


MOV AX,HighHandle 

MOV BX,LowHandle 

MOV DL,14h 

CALL DWORD PTR [DevHlp] 

JC ERROR 


the high order 16-bits of 
the lock handle returned 
from DevHlp service Lock 
is placed in AX 

the low order 16-bits of 
the lock handle are placed 
in BX 

code for DevHlp service 
Unlock 

address of device helper in 
ter face, extracted from 
Init 110 packet 

if carry is set, lock handle 
was invalid 


The segment is now movable and swappable. 
ERROR: 


Lock handle was invalid. 
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5.3.3 Semaphore Management Services at Strategy Time 

Serialization may also be accomplished between strategy routines, or 
between a strategy routine and a process, by use of semaphores. RAM 
semaphores may be allocated by a device driver, but addressability to the 
semaphore is the responsibility of the driver in the context in which the 
RAM semaphore is to be managed. System semaphores cannot be allo¬ 
cated by the device driver, but the system semaphore handle allocated to 
a process may be converted by the driver to a system-wide handle that is 
valid for use in any context. 

5.3.3.1 Get Handle for Semaphore Management (SemHandle, 8) 

Two kinds of semaphores are supported by the DevHlp services, system 
semaphores and RAM semaphores. FSRAM semaphores are not sup¬ 
ported. 

The address of a RAM semaphore is used as its key. If the address of a 
RAM semaphore is used as argument to SemHandle, the address is 
returned unchanged. A RAM semaphore is initialized to 0 when it is 
allocated. 

A system semaphore must be allocated by the calling process and its 
process-specific handle must be converted with SemHandle to a handle 
usable by the DevHlp services. This handle guarantees the semaphore 
against deletion in case of process death and must be released by the 
driver when no longer required. 

USAGE: 

MOV BX, LowWord LowWord is the low order 

word of the 32-hit system 
semaphore handle 
returned to the process by 
API call, DosCreateSem 

MOV AX, HighWord HighWord is the high 

order word of the 32-bit 
system semaphore handle 
returned to the calling 
process by API call, Dos¬ 
CreateSem. 
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MOV DH, 1 2 = Create new handle for 

' device driver use 

MOV DL, 8 code f or SemHandle service 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface^ extracted from 
Init HO packet 

JC ERROR error return taken 

AX,BX contains the 32-bit handle for the 
semaphore, suitable for use with device helper 
services. For RAM semaphores, AX,BX is un¬ 
changed. 

ERROR: 

AX contains the error code. The only defined 
error code is "Invalid Semaphore Handle." 

5.3.3.2 Release Handle for Semaphore Management (SemHandle, 8) 

If a system semaphore handle has been converted from a process-specific 
handle to a system-wide handle by SemHandle, that handle must be 
released when it is no longer required by the device driver. RAM 
semaphore addresses are unchanged by this call. 

USAGE: 

MOV BX,LowWord LowWord is the low order 

word of the 32-bit system 
semaphore handle 
returned to the process by 
DevHlp call, SemHandle. 

MOV AX, HighWord HighWord is the high 

order word of the 32-bit 
system semaphore handle 
returned to the calling 
process by DevHlp call, 
SemHandle . 

MOV DH,0 


MOV DL, 8 


0 = Release handle from 
device driver use 



250 WRITING OS/2 DEVICE DRIVERS 


Code for SemHandle ser¬ 
vice 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init IIO packet 

JC ERROR error return taken 

A system semaphore is no longer owned by the 
device driver. ARAM semaphore is unchanged. 

ERROR: 

AX contains the error code. The only defined 
error code is "Invalid Semaphore Handle." 


5.3.3.3 Request a Semaphore (SemRequest, 6) 

A strategy routine can request a semaphore. If the semaphore is.not 
available, the strategy routine blocks until the semaphore is released, or 
a specified time-out period expires. A RAM semaphore is considered 
available if the value contained in the double-word at the RAM 
semaphore’s address is 0. 

The time-out period is specified as 0 for no wait (return immediately 
with error if semaphore is not available), as -1 (OxFFFFFFFF) for in¬ 
definite wait, or in milliseconds for other intervals. 

If the process that owns a system semaphore terminates while the 
strategy routine is blocked waiting for that semaphore, the strategy 
routine resumes with error. 

USAGE: 

MOV BX, LowWord LowWord is the low order 

word of the 32-bit system 
semaphore handle 
returned by helper service 
SemHandle, or offset of 
virtual address of a RAM 
semaphore. 
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MOV AX,HighWord 

MOV CX,LowTimeout 

MOV DI,HighTimeout 

MOV DL,8 

CALL DWORD PTR [DevHlp] 

JC ERROR 
Semaphore is now 


HighWord is the high 
order word of the 32-bit 
system semaphore handle 
returned by helper service 
SemHandle, or selector of 
virtual address of a RAM 
semaphore. 

LowTimeout is the low 
order word of the 32-bit 
time-out period 

HighTimeout is the high 
order word of the 32-bit 
time-out period 

code for SemRequest ser¬ 
vice 

address of device helper in 
ter face, extracted from 
Init 110 packet 

error return taken 


owned by strategy routine. 


ERROR: 

AX contains the error code. Defined error codes 
are: 

"Semaphore Time-Out." 

"Semaphore Owner Died." 

"Invalid Handle." 

"Too Many Semaphore Requests." 


5.3.3.4 Release a Semaphore (SemClear, 7) 

Once ownership of a semaphore has been granted with SemRequest, the 
strategy routine has the responsibility to release the semaphore when it 
is no longer required. 
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USAGE: 


MOV BX,LowWord 

MOV AX,HighWord 

MOV DL, 7 

CALL DWORD PTR [DevHlp] 

JC ERROR 


LowWord is the low order 
word of the 32-bit system 
semaphore handle 
returned by helper service 
SemHandle, or offset of 
virtual address of a RAM 
semaphore. 

HighWord is the high 
order word of the 32-bit 
system semaphore handle 
returned by helper service 
SemHandle, or selector of 
virtual address of a RAM 
semaphore. 

code for SemClear service 


address of device helper in 
terface, extracted from 
Init HO packet 

error return taken 


Semaphore has been released by strategy routine 
and is available for ownership by other strategy 
routines or processes. 


ERROR: 


AX contains the error code. The only defined 
error code is "Invalid Semaphore Handle, or 
"Semaphore not Owned by Handle." 


5.3.4 Queue Management Services at Strategy Time 

Two types of queues are supported by the DevHlp interface: request 
packet queues and character queues. 

I/O request packets can be queued on a strategy queue. When a strategy 
routine that requires use of the device controller starts, it may disable 
interrupts and test the queue head double-word for the value 0. If the 
queue is empty, the strategy routine places the packet on the queue, starts 
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device I/O, and blocks. If the queue is active, the strategy routine pushes 
the packet on the queue, and blocks. Additional strategy packets can be 
allocated for temporary use by the device driver—they can be placed on 
strategy packet queues. 

Character queues are circular queues where characters are held until 
needed. Character queue handling routines are protected from interrupt 
interference. 

5.3.4.1 Place Request Packet onto Queue (PushReqPacket, 9) 

The request packet whose address is in ES:BX, is placed on the queue. A 
strategy packet queue is a double-word initialized to 0. The strategy 
routine must provide protection against interference from the interrupt 
service routines by disabling interrupts (processor instruction CLI) before 
using this service. 

USAGE: 


MOV SI,OFFSET QueueHead 

LES BX,RequestPacket 

MOV DL, 9 

CALL DWORD PTR [DevHlp] 


SI = Address of queue 
head doubleword. The 
queue is located in the 
main data segment for ad¬ 
dressability at interrupt 
time. 

address of request packet 
to be queued must be in 
ES:BX 

code for PushReqPacket 

address of device helper in 
terface, extracted from 
Init I/O packet 


At this point, the strategy packet has been placed 
on the request queue. 


5.3.4.2 Get Next Request Packet from Queue (PullReqPacket, OAh) 

The first packet waiting on the queue is removed from the queue, and its 
address is placed in ES:BX. If the queue is empty, an error code is 
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returned. The strategy routine must provide protection against inter¬ 
ference from the interrupt service routines by disabling interrupts 
(processor instruction CLI) before using this service. 

USAGE: 

MOV SI, OFFSET QueueHead SI = Address of queue 

head doubleword . The 
queue is located in the 
main data segment for ad¬ 
dressability at interrupt 
time . 

MOV DL, OAh code for PullReqPacket 

CALL DWORD PTR [DevHlp] 


JC ERROR 

At this point, the strategy packet has been 
removed from the queue and its address placed 
in ES:BX. 

ERROR: 

Request packet queue was empty. 

5.3.4.3 Remove Specified Packet from Queue (PullParticular, OBh) 

The request packet whose address is in ES:BX is removed on the queue. 
This service is used when a process terminates before I/O has been 
completed, or if a timer expires for the thread. The strategy routine must 
provide protection against interference from the interrupt service 
routines by disabling interrupts (processor instruction CLI) before usin g 
this service. 


address of device helper in¬ 
terface , extracted from 
Init I/O packet 

error Return 
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USAGE: 


MOV 

SI,OFFSET QueueHead 

SI = Address of queue 
head doubleword. The 
queue is located in the 
main data segment for ad¬ 
dressability at interrupt 
time. 

LES 

BX,RequestPacket 

Address of request packet 
to be removed must be in 
' ES:BX 

MOV 

DL,OBh 

code for PullParticular 

CALL 

DWORD PTR [DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init I/O packet 

JC 

ERROR 

error return 


At this point, the strategy packet whose address 
is in ES:BX has been removed from the queue. 

ERROR: 

Request packet queue was empty. 


5.3.4A Allocate Strategy Packet (AllocReqPacket, ODh) 

A strategy packet is allocated and can be used to represent a logical action 
—it may be queued on the request queue. If a single strategy routine must 
perform several I/O actions, it may prove convenient to represent each 
I/O action as a distinct request packet. All allocated request packets will 
then share the same thread, and must not signal I/O completion to the 
kernel; rather, each allocated request packet must be freed. 

The n um ber of available packets is small, as each packet has a tiled 
address. Packets should be used for as short a period as possible. 
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USAGE: 


MOV DH,WaitFlag WaitFlag determines 

whether process should 
wait if a packet is not 
available, or should 
return with error. 

0 = Wait for request packet 

1 - Return immediately 
with error if packet is not 
available 

MOV DL,ODh code for AliocReqPacket 


CALL DWORD PTR [DevHlp] 


JC ERROR 

At this point, a strategy packet has been allo¬ 
cated and its address placed in ES:BX. 


address of device helper in¬ 
terface , extracted from 
Init I/O packet 

error return 


ERROR: 


Register AX contains the error code. Only defined 
error code is "Request Packet not Available." 


5.3.4.5 Free Strategy Packet (FreeReqPacket, OEh) 

A request packet earlier allocated by AllocReqPacket must be released by 
the driver as quickly as possible, as the number of request packets 
available under OS/2 is limit ed. 

USAGE: 

LES BX, RequestPacket Address of request packet 

is placed in ES:BX. This 
packet must have been al¬ 
located earlier by Alloc¬ 
ReqPacket. 


MOV DL,OEh 


code for FreeReqPacket 



DEVICE HELPER ROUTINES 257 


CALL DWORD PTR [DevHlp] address of device helper in- 

terface, extracted from 
Init 110 packet 


At this point, the strategy packet earlier allo¬ 
cated by AllocFreePacket has been returned to 
the system pool of request packets. 


5.3.4.6 Sort Request Packet onto Queue (SortReqPacket, OCh) 

The request packet whose address is in ES:BX is placed on the queue in 
ascending order of sector number. This rather naive algorithm may 
actually degrade performance in many cases, as it always returns to the 
strategy packet with the lowest sector number—not the sector number 
closest to the currently processed sector number. Furthermore, cylinder 
structure is not considered. If a sorted request queue of any kind is used, 
the currently active request packet address must be preserved. 

USAGE: 


MOV SI,OFFSET QueueHead 

LES BX,RequestPacket 

MOV DL,OCh 

CALL DWORD PTR [DevHlp] 


SI = Address of queue 
head doubleword . The 
queue is located in the 
main data segment for ad¬ 
dressability at interrupt 
time. 

Address of request packet 
to be queued must be in 
ES:BX. 

code for SortReqPacket 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 


At this point, the strategy packet has been placed 
on the request queue. 
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5.3.4.7 Initialize Character Queue (Queuelnit, OFh) 

A character queue structure is composed of a 6-byte header and a queue 
buffer. The first word of the header must contain the length of the queue 
buffer before initialization. The queue structure is defined as follows: 


BUFFERLEN 

EQU N 

CHARQUEUE 

LABEL BYTE 

QSIZE 

DW BUFFERLEN 

QINDEX 

DW ? 

QCOUNT 

DW ? 


BUFFER DW BUFFERLEN DUP 

USAGE: 

MOV BX,OFFSET CHARQUEUE 

MOV DL,OFh 

CALL DWORD PTR [DevHlp] 


N is the length of the buff¬ 
er 


length of character buffer 
in bfytes 

Index of next character 
available to be removed 
from the queue. This field 
is not used by the device 
driver. 

Count of characters avail¬ 
able in the queue. Index of 
next character to be 
placed in queue is QIN- 
DEX+QCOUNT. This field 
is not normally used by 
the device driver. 

(?) array of characters that 
will be managed as a cir¬ 
cular queue 


BX = Address of character 
queue. The queue is lo¬ 
cated in the main data seg¬ 
ment for addressability at 
interrupt time. 

Code for Queuelnit 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 


The queue structure is initialized at this point. 
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5.3.4.8 Flush Character Queue (QueueFlush, lOh) 

QueueFlush initializes a character queue in identical fashion to Queue- 
Init. 


MOV BX,OFFSET CHARQUEUE 


MOV DL,lOh 


BX = Address of character 
queue. The queue is lo¬ 
cated in the main data seg 
ment for addressability at 
interrupt time. 

code for QueueFlush 


CALL DWORD PTR [DevHlp] 


address of device helper in¬ 
terface, extracted from 
Init HO packet 


The queue structure has been flushed at this 
point. 


5.3.4.9 Insert Character in Queue (QueueWrite, llh) 

The character in AL is placed in the queue. An error condition is reported 
if the queue is full. Interrupt protection is provided by this service. 

USAGE: 


MOV BX,OFFSET CHARQUEUE 

MOV AL,CHAR 

MOV DL,llh 

CALL DWORD PTR [DevHlp] 

JC ERROR 


BX = Address of character 
queue. The queue is lo¬ 
cated in the main data seg¬ 
ment for addressability at 
interrupt time. 

Value of character to be in¬ 
serted in queue is placed 
in AL. 

code for QueueWrite 

address of device helper in¬ 
terface , extracted from 
Init HO packet 

error took place 
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The character has been written to the queue, and 
may be later removed with QueueRead. 

ERROR: 

If this return was taken, the character was not in¬ 
serted into the queue because the queue was full. 


5.3.4.10 Return Character from Queue (QueueRead, 12h) 

The first character waiting in the queue is returned in AL. The error 
condition is raised if the queue is empty. Interrupt protection is provided 
by this service. 

USAGE: 

MOV BX,OFFSET CHARQUEUE 

MOV DL,12h 

CALL DWORD PTR [DevHlp] 

JC ERROR 

The first character in the queue was removed 
from the queue, and its value returned in AL. 

ERROR: 

If this return was taken, the character was not 
returned because the queue was empty. 


BX = Address of character 
queue. The queue is lo¬ 
cated in the main data seg¬ 
ment for addressability at 
interrupt time. 

code for QueueRead 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 

error took place 
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5.3.5 Timer Management at Strategy Time 

A timer entry point may be established by the strategy routine, which will 
immediately receive timer interrupts. This timer entry point may be used 
by the strategy routine for polling or time-out purposes. 

5.3.5.1 Register a New Timer Entry Point Called at Each Tick 

Establish an offset into the device driver main code segment to be called 
at each clock tick (SetTimer, lDh). Entry will be made with interrupts 
enabled, and must be dismissed with a far return instruction. All registers 
must be preserved. 

Note that any processing overhead in the timer routine is added to 
system overhead for each clock tick, reducing processor availability for 
all user processes. Furthermore, extremely excessive timer overhead will 
result in lost clock ticks. For these reasons, the timer code must be 
extremely efficient. 


USAGE: 


MOV AX,TimerOffset 

offset of timer entry point 
in code segment 

MOV DL,lDh 

code for SetTimer 

The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 


CALL DWORD PTR [DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init I/O packet 

JC ERROR 

error took place 


At this point, the timer entry point has been 
added to the list of entry points to be called each 
clock tick 


ERROR: 
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Now AX contains the error code. The only defined 
error code is "Timer Handler Disallowed." This 
error arises if: 

—System maximum number of timer entry 
points (32) is exceeded. 

—Timer entry point is already in use. 


5.3.5.2 Register an n-Tick Handler (TickCount, 33h) 

If called with a previously registered timer entry point, the timer tick 
count is modified in such a way that the timer routine is called every n 
tick counts. If called with an as yet unregistered timer entry point, 
TickCount establishes an offset into the device driver code segment to be 
called every n clock ticks. 

Entry to the timer routine will be made with interrupts disabled, and 
must be terminated with a far return instruction. 

Any processing overhead in the timer routine is added to system 
overhead every n clock ticks. While the impact of this overhead is much 
less than that of SetTimer above, which enters the clock routine every 
tick, the reduction of processor availability for all user processes must be 
considered. Extremely excessive timer overhead will result in lost clock 
ticks. For these reasons, the timer code must be extremely efficient. 

The number of ticks between calls to the timer entry point, n, may be 
any number from 1 to 65,535. Value n=0 represents 65,536 ticks. 


USAGE: 


MOV AX, TimerOf f set 

offset of timer entry point 
in code segment 

MOV BX,n 

set BX to the tick count 
desired between calls to 


the timer entry point . n=0 
means 65,536 ticks . 

MOV DL,33h 

code for TickCount 
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The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 

CALL DWORD PTR [DevHlp] 


JC ERROR 

At this point, the timer entry point has been 
added to the list of entry points to be called each 
clock tick 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Timer Handler Cannot be Set or 
Modified." This error arises for a new timer entry 
point if: 

—System maximum number of timer entry 
points (32) is exceeded. 

—Timer entry point is already in use 


address of device helper in¬ 
terface , extracted from 
Init HO packet 

error took place 


5.3.5.3 Remove Timer Handler (ResetTimer, lEh) 

After a timer handler has been utilized by the initialization routine, it is 
removed. A later strategy routine may reestablish the timer handler. 

Alternatively, the timer handler may continue running and perform no 
operations until needed for later processing. This technique has the 
disadvantage of unnecessarily increasing timer overhead and impacting 
system performance. 

USAGE: 

MOV AX, TimerOffset offset of timer entry point 

in main code segment 


MOV DL,lEh 


code for ResetTimer 
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The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface , extracted from 
Init I/O packet 

JC ERROR error took place 

At this point, this timer handler has been 
removed from the list of handlers to be called at 
timer interrupt time. 

\ 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Timer Handler not in Use." 


5.3.6 Character Monitor Services at Strategy Time 

Full character monitor support is available to the driver at strategy time. 
The driver can create an empty monitor chain, register monitor threads 
to the chain, and write data to the chain. The driver may deregister all 
threads associated with a process from a chain, and may delete an empty 
chain. 

5.3.6.1 Creating a Monitor Chain (MonitorCreate, lFh) 

This function creates an initially empty chain of monitors and associates 
the chain with a final buffer and a notification routine. The final buffer 
must allow 20 bytes of overload for the monitor dispatcher. 

A process opens a connection with a device monitor chain by means of 
the API call DosMonOpen, which is formatted by the file manager into an 
OPEN request packet and passed to the device driver strategy routine. 
The MON bit of the status word in the packet is set to indicate this as a 
monitor OPEN packet. A monitor chain is typically created in response to 
monitor OPEN requests. 
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USAGE: 



MOV 

AX, DS 


place selector value of 
main data segment in ES 

MOV 

ES, AX 



MOV 

SI,OFFSET 

FinalBuffer 

Place the segment'.offset 
address of the final buffer 
into ES:SI (note the un¬ 
usual use of register pair). 
The final buffer must 
reside in the main data 
segment. 

MOV 

AX, CS 


place selector value of 
main code segment in DS 

MOV 

DS, AX 



MOV 

DI,OFFSET 

Notify 

Place the segment‘.offset 
address of the notification 
routine in DS:DI (note the 
unusual use of register 
pair). The notification 
routine must reside in the 
main code segment. 

MOV 

AX, 0 


0=Create Monitor 

MOV 

DL,lFh 


code for MonitorCreate 

CALL 

DWORD PTR 

ES: [DevHlp] 

address of device helper in 
terface, extracted from 

Init I/O packet 

JC 

ERROR 




AX is the handle for the monitor chain. This 
value must be used to register monitors in 
response to the Kegister Monitor IOCtl. 

ERROR: 

The error code is placed in AX. The only defined 
error code is "Invalid Monitor Handle." 
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5.3.6.2 Deleting a Monitor Chain (MonitorCreate, lFh) 

A process closes a connection with a device monitor chain by means of the 
API call DosMonClose, which is formatted by the file manager into a 
CLOSE request packet and passed to the device driver strategy routine. 
The MON bit of the status word in the packet is set to indicate this as a 
monitor CLOSE packet. A monitor chain that was created by the monitor 
OPEN request typically is deleted in response to the corresponding 
monitor CLOSE request. All monitor threads on the chain should be 
deregistered (DevHlp service DeRegister) before the chain is destroyed. 


USAGE: 



MOV 

AX, DS 


place selector value of 
main data segment in ES 

MOV 

ES, AX 



MOV 

SI,OFFSET 

FinalBuffer 

Place the segment'.offset 
address of the final buffer 
into ES:SI (note the un¬ 
usual use of register pair). 
The final buffer must 
reside in the main data 
segment. 

MOV 

AX, CS 


place selector value of 
main code segment in DS 

MOV 

DS, AX 



MOV 

AX,CHAINHANDLE 

The handle for the chain 
that is to be deleted is 
placed in AX. This handle 
was returned by Monitor¬ 
Create. 

MOV 

DI,OFFSET 

Notify 

Place the segment'.offset 
address of the notification 
routine in DS'.DI (note the 
unusual use of register 
pair). The notification 
routine must reside in the 
main code segment. 

MOV 

DL,lFh 


code for MonitorCreate 
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address of device helper in¬ 
terface , extracted from 
Init I/O packet 


Here, the monitor chain has been deleted. 
Register AX is not preserved. 

ERROR: 

The error code is placed in AX. The only defined 
error code is "Invalid Monitor Handle." 


CALL DWORD PTR ES:[DevHlp] 

JC ERROR 


5.3.6.3 Register a Monitor to a Monitor Chain (Register, 20h) 

A process requests placement of a monitor thread on the monitor chain 
by means of the API call, DosMonReg that is translated by the file 
manager into the Register Monitor IOCtl (category OAh, function 40h). 
The device driver strategy routine registers the monitor thread to a 
driver-selector chain by means of the Register DevHlp call. Each monitor 
registered to the chain is now on line in order to process data sent through 
the chain. 

The size of the buffers allocated to hold character packets must include 
2 bytes of overhead for the monitor dispatcher. 

USAGE: 


MOV ES,BUFFERSEGMENT 


MOV SI,INPUTBUFFER 

MOV DI,OUTPUTBUFFER 


Both input and output buf¬ 
fers of the monitor thread 
are contained in a single 
segment. The address of 
this segment is placed in 
ES. 

The offset of the input buff¬ 
er within BUFFERSEG¬ 
MENT is placed in SI. 

The offset of the output 
buffer within BUFFER- 
SEGMENT is placed in DI. 
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MOV CX,PROCID 

MOV AX,CHAINHANDLE 

MOV DH,PlacementFlag 


CALL DWORD PTR [DevHlp] 

JC ERROR 


The process ID of the call¬ 
ing process is placed in 
CX. All monitors sharing 
the same process ID are 
deregistered simultaneous¬ 
ly • 

The handle for the chain 
on which the monitor 
thread is to be added is 
placed in AX. This handle 
was returned by Monitor- 
Create. 

Position in the monitor 
chain in which this 
monitor is to be placed. 
This value is given to the 
device driver by the 
Register Monitor IOCtl, 
and takes the following 
values: 

0 = No positional 
preference 

1 = Add to front of 
monitor chain (gets raw 
data) 

2 - Add to end of monitor 
chain (gets processed data) 

address of device helper in¬ 
terface, extracted from 
Init 110 packet 

error took place 


At this point, the monitor thread has been added 
to the list of monitors on the selected monitor 
chain. 


ERROR: 

Now AX contains the error code. The defined 
error codes are: 

"Invalid Monitor Handle." 

"Monitor Buffer too Small." 



DEVICE HELPER ROUTINES 269 


5.3.6.4 DeRegister Monitors from a Monitor Chain (Register, 21h) 

The device driver is expected to remove all monitors associated with the 
calling process from all chains in response to the monitor CLOSE packet. 
A process closes its connection with a device monitor chain by means of 
the API call, DosMonClose, which is formatted by the file manager into a 
CLOSE request packet and passed to the device driver strategy routine. 
The MON bit of the status word in the packet is set to indicate this as a 
monitor CLOSE packet. 

USAGE: 

MOV BX, PROCID The process ID of the call¬ 

ing process is placed in 
CX. All monitors sharing 
the same process ID are 
deregistered simultaneous¬ 
ly- 

MOV AX, CHAINHANDLE The handle for the chain 

from which the monitor 
threads are to be removed 
is placed in AX. This hand¬ 
le was returned by 
MonitorCreate. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR error took place 

At this point, all monitors sharing the process ID 
of the calling process on the selected monitor 
chain are deregistered. AX= count of threads 
remaining on the chain. 

ERROR: 

AX contains the error code. The only defined 
error code is "Invalid Monitor Handle." 
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5.3.6.5 Write a Monitor Character Packet to Monitor Chain 

The strategy routine writes a character to the monitor chain with this 
service (MonWrite, 22h). If the chain is empty, the character is written to 
the final buffer and the notification routine is called in the context of the 
driver routine that wrote the character, which may be ring 0 or interrupt 
context. Otherwise, the first monitor in the chain is activated in its 
process context. When it runs, it reads data from the chain and processes 
the character. The monitor thread then writes the processed character 
back to the chain, causing activation of the next monitor in the chain. 
When the last monitor writes back its character, the final buffer is filled 
with the processed character and the notification routine is called in the 
context of the monitor controlling thread (ring 0). 

The data written to the monitor chain is first enclosed in a packet 
defined by the device driver. The header of this packet is defined by the 
monitor dispatcher, and is one word long. This word should be set to 0 
before the MonWrite service is issued to write a character data packet. 
The low order byte of the monitor word may take the values 1 or 2 to 
represent the monitor open and close functions to the monitor chain. 

USAGE: 


MOV SI,OFFSET DATAPACKET 

MOV CX,PACKETSIZE 
MOV AX,CHAINHANDLE 


Place the address of the 
monitor character packet 
into SI. The first word of 
this packet is used by the 
monitor dispatcher. This 
packet must reside in the 
driver main data segment . 

size of monitor character 
packet is placed in CX 

The handle for the chain 
to which the monitor char¬ 
acter packet is to be writ¬ 
ten is placed in AX. This 
handle was returned by 
Monitor Create. 
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MOV DH,WaitFlag 


MOV DL,22h 

CALL DWORD PTR [DevHlp] 

JC ERROR 


WaitFlag determines 
whether the strategy 
routine should wait until 
sufficient buffer space is 
available in the monitor 
chain to write the charac¬ 
ter packet 9 or it should 
return immediately with 
error if the buffer is full . 

0 = Block until character 
packet is written to buffer 
(normal case) 

1 - Return with error if 
buffer space is not immedi¬ 
ately available 

code for MonWrite 

address of device helper in 
terface, extracted from 
Init HO packet 

error return 


Character packet has been written to monitor 
chain and will be processed through all monitor 
threads on the chain before being written to the 
final buffer and processed by the notification 
routine. 


ERROR: 

AX contains the error code. Two error codes are 
defined: 

"Invalid Monitor Handle" 

"Not Enough Memory" 

The "Not Enough Memory" error occurs if the 
buffer is full, or if a MonFlush request is pending. 


5.3.6.6 Flush Monitor Chain (MonFlush, 23h) 

The device driver issues MonFlush to flush the buffers of all monitor 
threads on the selected chain. This command is issued when the driver is 
required to flush its buffers, or in case of process termination. The monitor 
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chain will refuse all MonWrite requests until each monitor thread on the 
chain has processed the flush request. 

The MonFlush DevHlp service, formats a flush packet and places it on 
the monitor chain. A flush packet is a single word in length, with the flush 
bit set (bit 2). This packet is passed through all monitors on the chain, 
and when returned by the last monitor thread on the chain causes 
termination of the flush operation. 

USAGE: 


MOV AX,CHAINHANDLE 

MOV DL,23h 

CALL DWORD PTR [DevHlp] 


The handle for the chain 
to which the monitor char¬ 
acter packet is to be writ¬ 
ten is placed in AX. This 
handle was returned by 
Monitor Create. 

code for MonFlush 

address of device helper in 
terface, extracted from 
Init IfO packet 


5.3.7 Getting OS/2 Internal Variables at Strategy Time 

At strategy time, the strategy routine is executing in an underlying 
process context. The strategy routine may query OS/2 internal variables 
for global information pertaining to the system, or local variables for 
information specific to the underlying process. The strategy routine may 
also query the COM1 and COM2 ports to determine ownership of these 
devices, and may check the state of the Yield or TCYield flags to determine 
if a higher-priority thread is waiting to run. The strategy routine is not 
interruptible—causing even high-priority threads to wait until the 
strategy routine blocks. 

5.3.7.1 Return Pointer to DOS Variable (GetDosVar, 24h) 

EachADS/2-intemal variableds, associated with-a unique-and =bi-modal 
.address. This address is returned for a particular variable with GetDos- 
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Var. The address may then be used in the strategy mode, or in any other 
mode within the device driver. Table 5-4 lists the variable codes. 


Table 5-4: Variable Codes 


CODE DESCRIPTION 

1 Address of a word containing the bi-modal segment address of 
the global INFO segment. The global INFO segment contains 
the current date and time, the current screen group, and other 
miscellaneous data. The global INFO segment is described fur¬ 
ther in the appendices. 

2 Address of the offset, segment address of the local INFO segm- 
ment. The local segment contains the screen group number, 
process ID, and thread ID of the initialize process. 

3 Address of the two COM port words. The first word contains 0 if 
COM1 is owned, and the second word contains 0 if COM2 is 
owned. 

5 Address of the offset, segment address of the OS/2 reboot vec¬ 

tor. A JMP to this address will cause cold reboot of the operat¬ 
ing system. 

7 Address of the 1-byte Yield flag. The Yield flag is used to allow 
high-priority waiting tasks a time-slice when performing com¬ 
plex and non-critical computations in strategy mode. It should 
be sampled every 3 milliseconds to determine if such threads 
are waiting 

8 Address of the 1-byte Time Critical Yield flag. The Critical 
Yield flag is issued when a time-critical task is waiting. The 
flag is sampled to allow such tasks a time-slice when perform¬ 
ing complex and non-critical computations in kernel mode. This 
flag should be sampled every 3 milliseconds only if the Yield 
flag is not sampled, as the Yield flag is set whenever the Time 
Critical Yield flag is set. 


USAGE: 


MOV AL,VarCode Place the variable code of 

the variable whose ad¬ 
dress is required in AL . 
The variable code is 
drawn from the above 
table . 
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MOV DL, 24h Code for DosGetVar. 


CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init HO packet 


JC ERROR 

The address of the variable is returned in AX:BX, 
AX containing the segment/selector, and BX con¬ 
taining the offset 

ERROR: 

Variable code does not correspond to an OS/2 vari¬ 
able. 


5.3.8 Communicating Between Device Drivers 

A link may be established between two device drivers, which we will term 
the source and target device drivers. The source device driver will call 
the target device driver. The target device driver is a character device 
driver addressed by an eight-character name and must have the IDC bit 
set in its driver header. The AttachDD DevHlp call will return the IDC 
entry point and main data segment address for the target driver. These 
values are returned for both real and protect mode. 

To utilize the IDC entry point, the source driver determines if it is 
functioning in real or protect mode, sets registers accordingly, and calls 
the target driver with a FAR CALL. The target driver is responsible for 
interpretation and/or saving of registers, and terminating with a far 
return. 

USAGE: 

MOV BX, DDnameOf f set Offset in current main 

data segment of 8-charac¬ 
ter blank-filled name of 
previously loaded charac¬ 
ter device driver. 


MOV DI,IDCOffset 
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offset in current main 
data segment of IDC data 

MOV DL, 2Ah code for AttachDD 

The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR error took place 

«/ 

At this point, the IDC data structure in the main 
data segment has been filled in, and can be used 
to call the IDC entry of the target device driver. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Device driver not found or does not 
support IDC." 

The format of the IDC data structure is displayed in Table 5-5. 


Table 5-5: IDC Data Structure 


OFFSET 

LENGTH 

DESCRIPTION 

0 

WORD 

Offset of IDC entry point. 

2 

WORD 

Real-mode CS of IDC driver. 

4 

WORD 

Real-mode DS of IDC driver. 

5 

WORD 

Offset of IDC entry point. 

8 

WORD 

Protect-mode CS of IDC driver. 

OAh 

WORD 

Protect-mode DS of IDC driver. 
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5.3.9 Interrupt Management Helper Services 

Normally, all interrupt management will take place at initialization time. 
An interrupt service routine may be established or removed by the 
strategy routine. It might be established in response to a Device OPEN 
request, and removed when the corresponding Device CLOSE is received. 

5.3.9.1 Intercept Hardware Interrupt (SetIRQ, lBh) 

Interrupt requests generated by device controllers are arbitrated by the 
interrupt controller. The interrupt controller prioritizes interrupt re¬ 
quests so only the highest priority request will be granted. Management 
of the interrupt controller happens in a partially hardware-independent 
way with SetIRQ and EOI. The EOI instruction dismisses an interrupt, 
and is rarely used by a strategy routine. 

In the AT and PS/2 machines, the interrupt controller is a cascaded 
master/slave interrupt controller arrangement. IRQ2 of the master 8259 
is activated by the slave 8259. Each of the master interrupt levels 0-7 is 
associated with an interrupt vector in the range 50h-57h. Similarly, each 
of the slave interrupt levels 8-OFh is associated with an interrupt vector 
in the range 70h-77h. SetIRQ associates an interrupt level with an 
interrupt entry point within the device driver, relieving the driver writer 
of the responsibility of knowing association between IRQ level and inter¬ 
rupt vector. The driver writer need have knowledge only of the IRQ level. 
Some of the preassigned IRQ levels are listed in Table 5-6. 


Table 5-6: Preassigned IRQ Levels 


8259 

IRQ 

DEVICE 

Master 

0 

Real-time clock (18 milliseconds), received by 
compatibility box only. 


1 

Keyboard interrupt. 


2 

Slave 8259 request. 


3 

COM2 serial port. 


4 

COM1 serial port. 


5 

LPT2 parallel port. 


6 

Floppy disk. 
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Table 5-6: Preassigned IRQ Levels 

8259 

IRQ 

DEVICE 


7 

LPT1 parallel port. 

Slave 

8 

Real-Time Clock (31.25 milliseconds), used for 
protect-mode scheduling. Received every .98 mil¬ 
liseconds by compatibility box. 


9 

EGA scan line interrupt, rarely used. 


OAh 

unused. 


OBh 

unused. 


OCh 

unused. 


ODh 

80287 Coprocessor. 


OEh 

Hard Disk. 


OFh 

unused. 


When the processor interrupt flag allows interrupts (is set), and when 
a hardware interrupt is requested by a device controller (and is the 
high est priority interrupt of all pending requests), interrupts are disabled 
and control is passed to the entry point of the device driver specified by 
the SetIRQ request. 

OS/2 supports shared interrupts where several device drivers share a 
single interrupt level. A single driver in which the interrupt is arbitrated 
among several logical devices is not considered shared. In the case of 
shared interrupts, the interrupt entry of each device driver is called in 
turn with interrupts enabled. It is the responsibility of each device driver 
to deter min e if this interrupt is meant for this driver and if so to perform 
appropriate processing. 

A shared interrupt is not available for exclusive use and an interrupt 
which has been assigned exclusively to a driver cannot be used by any 
other driver. 

Shared interrupts require the interrupt controller to be level-triggered, 
so that multiple, simultaneous interrupt requests are not lost. This 
architecture is supported by the PS/2. The AT supports an edge-triggered 
interrupt controller. If two devices request interrupts on a shared line, 
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the controller can only latch one, and "forgets" the second interrupt 
request. Consequently, AT interrupts may not be shared. 

Interrupts that are used to cascade the slave 8259 interrupt controller 
are not available for the device driver. IRQ2 is reserved for this use on 
the AT and PS/2 machines. Interrupts that are received by the interrupt 
manager for which a SetIRQ has not been issued, cause OS/2 to per¬ 
manently disable that IRQ level at the PIC. 


USAGE: 


MOV AX,Offset 

offset in code segment of 
interrupt entry point 

MOV BX,IRQnum 

interrupt level (O-OFh) 

MOV DH,ShareFlag 

shared interrupt flag: 

0 = not shared 

1 = shared 

MOV DL,lBh 

code for SetIRQ 

DS must contain device driver data segment 
value. This value will be placed in DS before in¬ 
terrupt entry is called. 


CALL DWORD PTR [DevHlp] 

address of device helper in 
terface, extracted from 

Init 1/ 0 packet 

JC ERROR 

if carry is set, an error oc¬ 
curred 


At this point, IRQ has been intercepted. 

ERROR: 

AX contains the error code. The only error avail¬ 
able is "IRQ is not Available." 



DEVICE HELPER ROUTINES 279 


5.3.9.2 Remove Hardware Interrupt Handler (UnSetIRQ, ICh) 

If a hardware interrupt (IRQ) is needed only temporarily (unusual case), 
the strategy routine may issue SetIRQ for that IRQ level, program the 
device controller, block waiting for the interrupt service to complete, and 
then remove the interrupt handler. 


USAGE: 


MOV BX,IRQnum 

hardware interrupt level 
(0 - OFh) of interrupt to he 
removed 

MOV DL,ICh 

code for UnSetIRQ 

DS must contain device driver data segment 
value before this call. 


CALL DWORD PTR [DevHlp] 

address of device helper in 
terface, extracted from 

Init I/O packet 


JC ERROR 

Here the interrupt routine has been removed. 
ERROR: 

Register AX contains the error code. Currently 
defined code is "IRQ level not owned by device 
driver." 


5.4 Interrupt Time Helper Services 

Available device helper services are limited at interrupt time. Because an 
interrupt takes place in the context of the running thread, the routine 
must be prepared to map memory addresses independently of the 
real/protect context and of any local process table. An interrupt routine 
does not have a process context, therefore it cannot suspend. All memory 
that the interrupt routine accesses must be locked to avoid suspension. 
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The interrupt service routine terminates with a FAR return instruction, 
and doesn’t need to preserve registers. 

The character monitor notification routine is typically called in the 
context of the monitor dispatcher, and can execute all strategy mode 
DevHlp services. However, if a character is written to a monitor chain in 
interrupt context and the monitor chain is empty, the notification routine 
is called in interrupt context. In this case, only those routines available 
to the interrupt context may be used in the notification routine. The 
notification routine terminates with a FAR return instruction, and doesn’t 
need to preserve registers. 

The timer routine is called every clock tick, or every n clock ticks. This 
routine runs in protect mode, essentially in interrupt context, except that 
interrupts are enabled and all registers must be preserved. All DevHlp 
services available to interrupt routines are available to the timer routine. 
The timer routine terminates with a FAR return instruction, and must 
restore the values of any registers it has used. 

The IDC routine may be called from another device driver in strategy 
or interrupt context, or in initialize context. Use only DevHlp routines 
supported by all possible modes of entry. The IDC routine terminates with 
a FAR return instruction. The interpretation or restoration of registers is 
established by convention between the calling and called device drivers. 

5.4.1 Process Management at Interrupt Time 

The interrupt service routine may not block, and so its process manage¬ 
ment functions are limited to starting suspended processes, and context 
switch from real mode to protect mode. 

5.4.1.1 Resume Previously Blocked Strategy Routine (Run, 5) 

The Run service unblocks all strategy routines that are blocked on the 
same 32-bit value. While every effort is made to ensure uniqueness of the 
32-bit value, the possibility of erroneous awakening should be considered 
in coding the Block service. 

USAGE: 


MOV BX,LowWord 
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MOV AX,HighWord 

MOV DL, 5 

CALL DWORD PTR [DevHlp] 

JZ NONEWAITING 


LowWord is the low order 
word of the 32-bit value 
on which the block was is¬ 
sued. 

HighWord is the high 
order word of the 32-bit 
value on which the block 
was issued. 

code for Run service 

address of device helper in 
terface, extracted from 
Init HO packet 

no blocks were waiting 
with this 32-bit identifier 


AX contains the count of those strategy routines 
that were waiting on this identifier. 


NONEWAITING: 

No strategy routines were waiting on this 32-bit 
identifier. 


5.4.1.2 Flag I/O Completion in Kernel (DevDone, 1) 

A strategy routine may return without having set the DONE bit of the 
STATUS word of the strategy packet, in which event the packet is blocked 
by the kernel on the tiled address of the packet (contained in ES:BX). In 
this case the routine that awakens the strategy routine will set the error 
status, and then issue the DevDone service with ES:BX containing the 
strategy packet address. The kernel sets the DONE bit and unblocks the 
strategy routine, which returns to the calling thread. 

USAGE: 

LES BX, request Place tiled address of 

strategy packet in ES:BX. 
The DONE bit of this pack¬ 
et will be set, and the 
strategy routine cor¬ 
responding to this packet 
will run to completion. 
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MOV DL, 1 code for DevDone 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init HO packet 

5.4.1.3 Switch from Real Mode to Protect Mode (RealToProt, 2Fh) 

If the interrupt service routine is called in the compatibility box context, 
the driver may switch from real mode to protect mode. The driver must 
switch back to real mode before returning from the interrupt service 
routine (DevHlp service, ProtToReal). This feature is of limited utility on 
80286 machines as it takes about 3 milliseconds to complete the required 
switch from protect mode back to real mode. 

USAGE: 


MOV DL, 2Fh code for RealToProt 

DS must contain the real-mode segment value for 
the main data segment. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR error took place 

At this point, processor mode has been switched 
from real to protect mode. All real-mode stored 
pointers are invalid. The contents of DS have 
been changed for protect-mode operation, and if 
ES contained the segment value for the real¬ 
mode data segment, its value is also changed to 
the corresponding protect-mode value. 

ERROR: 

Now AX contains the error code. The only defined 
error code is "Mode has not been Changed." 
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5.4.1.4 Return to Real Mode from Protect Mode (ProtToReal, 30h) 

If the driver is executing in protect mode as a result of using the DevHlp 
service RealToProt, the driver must return to real-mode context before 
returning from the interrupt service routine. On 80286 machines it takes 
about 3 milliseconds to complete the required switch from protect mode 
back to real mode. 

USAGE: 


MOV DL, 30h code for RealToProt 

DS must contain the protect-mode segment value 
for the main data segment. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init 110 packet 


JC ERROR 


error took place 


At this point, processor mode has been returned 
to real mode from protect mode. All protect-mode 
stored pointers are invalid. The contents of DS 
have been changed for real-mode operation, and 
if ES contained the segment value for the protect 
mode data segment, its value is also changed to 
the corresponding real-mode value. 


ERROR: 

Now AX contains the error code. The only defined 
error code is "Mode has not been Changed". 


5.4.2 Memory Management at Interrupt Time 

The interrupt service routine may not block, and this prohibits allocation 
of memory, locking memory, or even access of unlocked memory. 

The interrupt service routine executes in the underlying process con¬ 
text, which may be that of any active thread, or the real-mode context of 
the compatibility box. The only mode-independent method of addressing 
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memory is to convert a pair of 24-bit physical addresses to selector:offset 
pairs using PhysToVirt. This approach suffers from logistical problems in 
that other stored addresses cannot be considered valid during the trans¬ 
lation, the constructed pointers cannot be stored, and the order of conver¬ 
sion of the pair of addresses may be significant. 

If the interrupt routine is determined, by exa minin g the machine 
status word, to be operating in protect mode, all global selectors are valid. 
If the strategy routine had previously locked any addresses to be accessed 
by the interrupt service routine and had mapped those addresses to global 
descriptors, the memory at those addresses may be accessed at interrupt 
time using the mapped global selectors. 

5.4.2.1 Map to Global Selector (PhysToGDTSelector, 2Eh) 

A global selector allocated at initialize time by AllocGDTSelector is not 
valid for use until a segment of physical memory has been mapped to it. 
Similarly, a segment of physical memory cannot be addressed unl ess 
mapped to a selector or segment. Once mapped to a global selector, the 
segment of memory can be addressed in protect mode in any context, 
whether interrupt, strategy or other context. 

USAGE: 


MOV SI,GDTArraySelector 


MOV AX,HighStart 


MOV BX,LowStart 


Global selector value from 
global selector list allo¬ 
cated by AllocGDTSelector 
is placed in SI. 

High order 16-bits of start¬ 
ing address of physical 
memory previously allo¬ 
cated by AllocPhys, or lock¬ 
ed and converted from 
virtual to physical ad¬ 
dress. 

Low order 16-bits of start¬ 
ing address of physical 
memory previously allo¬ 
cated by AllocPhys , or lock¬ 
ed and converted from 
virtual to physical ad¬ 
dress. 
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MOV 

CX,Length 

Length is the length of the 
segment of memory to be 
mapped . Value 0 repre¬ 
sents 64K bytes (65,536), 

MOV 

DL,2Eh 

code for 

PhysToGDTSelector 

CALL 

DWORD PTR [DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init HO packet 

JC 

ERROR 

error took place 


At this point, the physical memory whose start 
address was contained in AX, BX has been 
mapped to the selector whose address is con¬ 
tained in DS:SI. 

ERROR: 

Now AX contains the error code. The only defined 
error codes are "Invalid address" or "Invalid 
Selector." 


5.4.2.2 Temporary, Mode-Independent Map (PhysToVirt, 15h) 

For protect-mode operations, OS/2 reserves two GDT entries for use by 
PhysToVirt within the IRQ level at which the interrupt routine is run¬ 
ning. One is reserved for mapping physical memory to DS, and the other 
for mapping physical memory to ES. PhysToVirt maps a physical address 
to the selected GDT entry and places its selector in the selector register 
DS or ES. This selector can be stored, but will be remapped if the 
PhysToVirt is used to map the same selector register (DS or ES). This 
condition may occur if nested interrupts are allowed by the interrupt 
service routine. The offset register associated with the mapped selector 
register (DS:SI or ES:DI) is set to 0. 

For real-mode operations that map physical addresses below 1M, the 
segment:offset value is placed in DS:SI or ES:DI. These addresses may 
be stored for later use in real mode. 

The mapping of physical addresses in high memory on the 80386 causes 
a context switch to protect-mode operation. This invalidates previous 
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real-mode mappings, or any real-mode segment values. However, if the 
main data segment address is contained in either DS or ES, the DS or ES 
value is converted to a selector value still pointing to the main data 
segment. The mapping must be terminated with UnPhysToVirt before the 
strategy routine may block. 

On the 80286, mapping of physical addresses in high memory causes 
the use of the undocumented processor LOADALL instruction, which 
loads shadow registers that enable addressing of high memory from real 
mode. The segment register is no longer valid and cannot be saved or 
restored and therefore, PhysToVirt disables interrupts to prevent inad¬ 
vertent modification of this register. UnPhysToVirt must be called to 
terminate the mapping before interrupts are enabled (or the routine 
blocks). DevHlp services cannot be used while this mapping is in effect. 


USAGE: 


MOV 

PUSH 

PUSH 

BP, SP 

WORD PTR [DevHlp+2] 

WORD PTR [DevHlp] 

save address of DevHlp 
routine for use during 
mapped context 

MOV 

AX,highaddr 

high order 16 bits of ad¬ 
dress of start of physical 
memory to be mapped 

MOV 

BX,lowaddr 

low order 16 bits of ad¬ 
dress of start of physical 
memory to be mapped 

MOV 

CX,length 

Desired length of segment. 
Since segment lengths are 
limited to 64K, a single 
large memory allocation 
may require several seg¬ 
ments to map it in its en¬ 
tirety, Value 0 means 
maximum segment size of 
64K (65,536), 
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MOV DH,ResultCode 


MOV DL,15h 


ResultCode determines 
where returned seg¬ 
ment /offset pointer will he 
placed . This code serves to 
select which of the two 
global selectors will he 
used. 

0 = return pointer in 
DS:SI. 

1 = return pointer in 
ES:DI. 

code for PhysToVirt 


CALL DWORD PTR [BP-4] 


address of device helper in¬ 
terface, extracted from 
Init I/O packet 


JC ERROR if carry set , error in map¬ 

ping 

Now returned segment/selector and offset pointer 
to mapped memory is located in DS:SI or in 
ES:DI. 


JZ MODECHANGE 

No mode change has taken place, so all stored ad¬ 
dresses remain valid. 


MODECHANGE: 

Mode was changed from real mode to protect 
mode. Any real-mode stored pointers, or pre¬ 
viously mapped pointer in other segment 
register, are invalid and must be remapped. 

ERROR: 

Now AX contains the error code. The only pos¬ 
sible error code is "Invalid Address." 
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5.4.2.3 Terminate Mode-Independent Map (UnPhysToVirt, 32h) 

Only one call to UnPhysToVirt is made to release the mapping context, 
even if many calls to PhysToVirt were made (note that only two addresses 
are simultaneously valid). 

UnPhysToVirt must be called before returning from the in itialization 
routine. If UnPhysToVirt is called in the protect-mode context created by 
mapping an address above 1M on a 80386 processor, the context is 
returned to real mode. 

DS is restored to point to the main data segment. The contents of ES 
are not preserved. 

USAGE: 

MOV DH, 32h code for UnPhysToVirt 

CALL DWORD PTR [BP-4] address of device helper in- 

ter face, extracted from 
Init HO packet 

MOV SP,BP restore stack pointer 

Both selectors have now been released. 

JZ MODECHANGE 

No mode change has taken place, so interrupt 

flag has not been altered. 

MODECHANGE: 

Mode was changed from real mode to protect 

mode. Interupt flag should be restored. 


5.4.3 Semaphore Management Services 

The interrupt service routine cannot request a semaphore, as blocking is 
prohibited. The interrupt service routine may obtain a handle by which 
it may refer to system semaphores, clear a semaphore, or release the 
handle. 
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5.4.3.1 Get Handle for Semaphore Management (SemHandle, 8) 

Two kinds of semaphores are supported by the DevHlp services, system 
semaphores and RAM semaphores. FSRAM semaphores are not sup¬ 
ported. 

The address of a RAM semaphore is used as its key. If the address of a 
RAM semaphore is used as an argument to SemHandle, the address is 
returned unchanged. A RAM semaphore is initialized to 0 when it is 
allocated. 

A system semaphore must be allocated by the calling process, and its 
process-specific handle must be converted with SemHandle to a handle 
usable by the DevHlp services. This handle guarantees the semaphore 
against deletion in case of process death and it must be released by the 
driver when no longer required. 


USAGE: 


MOV 

BX,LowWord 

LowWord is the low order 
word of the 32-bit system 
semaphore handle 
returned to the process by 
API call, DosCreateSem. 

MOV 

AX,HighWord 

HighWord is the high 
order word of the 32-bit 
system semaphore handle 
returned to the calling 
process by API call, Dos¬ 
CreateSem. 

MOV 

DH, 1 

1 = Create new handle for 
device driver use 

MOV 

DL, 8 

code for SemHandle service 

CALL 

DWORD PTR [DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init I/O packet 


JC 


ERROR 


error return taken 
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AX,BX contains the 32-bit handle for the 
semaphore, suitable for use with device helper 
services. For RAM semaphores, AX,BX is un¬ 
changed. 

ERROR: 

AX contains the error code. The only defined 
error code is "Invalid Semaphore Handle." 


5.4.3.2 Release Handle for Semaphore Management (SemHandle, 8) 

If a system semaphore handle has been converted from a process-specific 
handle to a system-wide handle by SemHandle, that handle must be 
released when it is no longer required by the device driver. RAM 
semaphore addresses are unchanged by this call. 

USAGE: 


MOV BX,LowWord 

MOV AX,HighWord 

MOV DH, 0 
MOV DL, 8 

CALL DWORD PTR [DevHlp] 


LowWord is the low order 
word of the 32-bit system 
semaphore handle 
returned to the process by 
DevHlp call , SemHandle. 

HighWord is the high 
order word of the 32-bit 
system semaphore handle 
returned to the calling 
process by DevHlp, call 
SemHandle. 

0 = Release handle from 
device driver use 

code for SemHandle service 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 


JC ERROR 


error return taken 
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A system semaphore is no longer owned by the 
device driver. ARAM semaphore is unchanged. 

ERROR: 

AX contains the error code. The only defined 
error code is "Invalid Semaphore Handle." 


5.4.3.3 Release a Semaphore (SemClear, 7) 

An interrupt routine may be charged with the responsibility to release a 
semaphore earlier requested in a strategy routine (SemRequest). 

USAGE: 


MOV BX,LowWord 


MOV AX,HighWord 


MOV DL, 7 


LowWord is the low order 
word of the 32-bit system 
semaphore handle 
returned by helper service 
SemHandle, or offset of 
virtual address of a RAM 
semaphore. 

HighWord is the high 
order word of the 32-bit 
system semaphore handle 
returned by helper service 
SemHandle, or selector of 
virtual address of a RAM 
semaphore. 

code for SemClear service 


CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init HO packet 

JC ERROR error return taken 

Semaphore has been released by strategy 
routine, and is available for ownership by other 
strategy routines or processes. 


ERROR: 
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AX contains the error code. The only defined 
error code is "Invalid Semaphore Handle," or 
"Semaphore not Owned by Handle." 


5.4.4 Queue Management Services 

Two types of queues are supported by the DevHlp interface, request 
packet queues and character queues. 

Strategy packets may be removed from a strategy queue. If the inter¬ 
rupt service routine has issued EOI allowing nested interrupts, it should 
disable interrupts before accessing the strategy queue. Character queues 
are circular queues into which characters are held until needed. Charac¬ 
ter queue handling routines are protected from interrupt interference. 

5.4.4.1 Get Next Request Packet from Queue (PullReqPacket, OAh) 

The first packet waiting on the queue is removed from the queue, and its 
address is placed in ES:BX. If the queue is empty, an error code is 
returned. Protection against nested interrupts must be provided by the 
interrupt service routine by disabling interrupts before using this service 
(processor instruction CLI). 

USAGE: 

MOV SI,OFFSET QueueHead 


MOV DL,OAh 

CALL DWORD PTR [DevHlp] 


JC ERROR 


Place address of strategy 
queue head double word 
in DS:SI. The queue must 
be located in the main 
data segment to be acces¬ 
sible in real mode. 

code for PushReqPacket 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 

error Return 



DEVICE HELPER ROUTINES 293 


At this point, the strategy packet has been 
removed from the queue and its address placed 
in ES:BX. 

ERROR: 

Request packet queue was empty. 


5A.4.2 Remove Specified Packet from Queue (PullParticular, OBh) 

The request packet whose address is in ES:BX is removed on the queue. 
This service is used when a timer expires for the thread. Protection 
against nested interrupts must be provided by the interrupt service 
routine by disabling interrupts before using this service—processor in¬ 
struction CLI. 

USAGE: 

MOV SI, OFFSET QueueHead Place address of strategy 

queue head double word 
in DS:SI. The queue must 
be located in the main 
data segment to be acces¬ 
sible in real mode . 

LES BX, RequestPacket address of request packet 

to be removed must be in 
ES:BX 

MOV DL, OBh code for PullParticular 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 

JC ERROR error Return 

At this point, the strategy packet whose address 

is in ES:BX has been removed from the queue. 

ERROR: 


Request packet queue was empty. 
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5A.4.3 Initialize Character Queue (Queuelnit, OFh) 

A character queue structure is composed of a six-byte header and a queue 
buffer. The first word of the header must contain the length of the queue 
buffer before initialization. The queue structure is defined as follows: 


BUFFERLEN 

EQU 

N 

N is the length of the buff¬ 
er 

CHARQUEUE 

LABEL 

BYTE 


QSIZE 

DW 

BUFFERLEN 

length of character buffer 
in bytes 

QINDEX 

DW ? 


Index of next character 
available to be removed 
from the queue. This field 
is not used by the device 
driver. 

QCOUNT 

DW ? 


Count of characters avail¬ 
able in the queue. Index of 
next character to be 


placed in queue is QIN- 
DEX+QCOUNT. This field 
is not normally used by 
the device driver. 

BUFFER DW BUFFERLEN DUP (?) Array of characters that 

will be managed as a cir¬ 
cular queue. 

USAGE: 

MOV BX, OFFSET CHARQUEUE Place address of character 

queue in DS:BX. The char¬ 
acter queue is located in 
the main data segment to 
be addressable at inter¬ 
rupt time. 

MOV DL, OFh code for Queuelnit 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init I/O packet 


The queue structure is initialized at this point. 



DEVICE HELPER ROUTINES 295 


5 AAA Flush Character Queue (QueueFlush, lOh) 

QueueFlush initializes a character queue in identical fashion to Queue- 
Init. A character queue structure is composed of a six-byte header and a 
queue buffer. The first word of the header must contain the length of the 
queue buffer before flush. The queue structure is defined as follows: 

BUFFERLEN EQU N N is the length of the buff¬ 

er 

CHARQUEUE LABEL BYTE 


QSIZE 

DW 

BUFFERLEN 

QINDEX 

DW 

? 

QCOUNT 

DW 

? 

BUFFER 

DW 

BUFFERLEN 

USAGE: 



MOV BX, 

OFFSET 

CHARQUEUE 


MOV DL,lOh 


length of character buffer 
in bytes 

Index of next character 
available to be removed 
from the queue. This field 
is not used by the device 
driver. 

Count of characters avail¬ 
able in the queue. Index of 
next character to be 
placed in queue is QIN- 
DEX+QCOUNT. This field 
normally is not used by 
the device driver. 

DUP (?) Array of characters which 
will be managed as a cir¬ 
cular queue. 


Place address of character 
queue in DS:BX. The char¬ 
acter queue is located in 
the main data segment to 
be addressable at inter¬ 
rupt time. 

code for QueueFlush 


CALL DWORD PTR [DevHlp] 
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address of device helper in¬ 
terface , extracted from 
Init 110 packet 

The queue structure is flushed at this point. 


5AA.5 Insert Character in Queue (QueueWrite, llh) 

The character in AL is placed in the queue. An error condition is reported 
if the queue is full. Interrupt protection is built into this service and 
doesn’t need to be provided by the driver. 

USAGE: 


MOV BX,OFFSET CHARQUEUE 

MOV AL,CHAR 

MOV DL,llh 

CALL DWORD PTR [DevHlp] 

JC ERROR 


Place address of character 
queue in DS:BX. The char¬ 
acter queue is located in 
the main data segment to 
be addressable at inter¬ 
rupt time. 

value of character to be in¬ 
serted in queue is placed 
in AL 

code for QueueWrite 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 

error took place 


The character has been written to the queue and 
may be removed later with QueueRead. 

ERROR: 

If this return was taken, the character was not in¬ 
serted into the queue because the queue was full. 
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5.4.4.6 Return Character from Queue (QueueRead, 12h) 

The first character waiting in the queue is returned in AL. The error 
condition is raised if the queue is empty. Interrupt protection is built into 
this service and doesn’t need to be provided by the driver. 

USAGE: 

MOV BX,OFFSET CHARQUEUE 

MOV DL,12h 

CALL DWORD PTR [DevHlp] 

JC ERROR 

The first character in the queue was removed 
from the queue, and its value returned in AL. 

ERROR: 

If this return was taken, the character was not 
returned because the queue was empty. 


Place address of character 
queue in DS:BX. The char¬ 
acter queue is located in 
the main data segment to 
he addressable at inter¬ 
rupt time . 

code for QueueRead 

address of device helper in¬ 
terface , extracted from 
Init I/O packet 

error took place 


5.4.5 Timer Management at Interrupt Time 

Timer entry points cannot be created by the interrupt service routine. The 
number of ticks between calls to a timer entry point can be modified, and 
the timer entry point may be removed. 

5.4.5.1 Call Timer Handler Each n Ticks (TickCount, 33h) 

The timer tick count of a previously registered timer entry point count is 
modified in such a way that the timer routine is called every n tick counts. 



298 WRITING OS/2 DEVICE DRIVERS 


Entry to the timer routine will be made with interrupts disabled, and 
must be terminated with a far return instruction. 

Any processing overhead in the timer routine is added to system 
overhead every n clock ticks. While the impact of this overhead is much 
less than that of SetTimer (which enters the clock routine every tick), the 
reduction of processor availability for all user processes must be con¬ 
sidered. Furthermore, extremely excessive timer overhead will result in 
lost clock ticks. For these reasons, the timer code must be extremely 
efficient. 

The number of ticks between calls to the timer entry point, n, may be 
any number from 1 to 65,535. Value n=0 represents 65,536 ticks. 

USAGE: 


MOV 

AX,TimerOffset 

offset of timer entry point 
in code segment 

MOV 

BX, n 

Set BX to the tick count 
desired between calls to 
the timer entry point. n=0 
means 65,536 ticks. 

MOV 

DL,33h 

code for TickCount 

The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 


CALL 

DWORD PTR [DevHlp] 

address of device helper in 
terface, extracted from 

Init I/O packet 

JC 

ERROR 

error took place 


At this point, the timer entry point has been 
added to the list of entry points to be called each 
clock tick. 


ERROR: 


Now AX contains the error code. The only defined 
error code is "Timer Handler Cannot be Set or 
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Modified." This error arises for a new timer entry point 
if: 

—System maximum number of timer entry 
points (32) is exceeded. 

—Timer entry point is already in use. 


5.4.5.2 Remove Timer Handler (ResetTimer, lEh) 

A timer entry point may be removed at interrupt time. For example, an 
interrupt service routine might want to cancel a time-out routine, or the 
timer routine itself might want to cancel further timer requests. 


USAGE: 


MOV AX,TimerOffset 

offset of timer entry point 
in main code segment . 

MOV DL,lEh 

code for ResetTimer 

The DS register must contain the device driver 
data segment. If DS has been changed for any 
reason, restore before this call. 


CALL DWORD PTR [DevHlp] 

% 

address of device helper in 
terface , extracted from 

Init I/O packet 

JC ERROR 

error took place 


At this point, this timer handler has been 
removed from the list of handlers to be called at 
timer interrupt time. 


ERROR: 

Now AX contains the error code. The only defined 
error code is "Timer Handler not in Use." 
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5.4.6 Character Monitor Services at Interrupt Time 

The interrupt service routine is permitted to write a character packet to 
a monitor chain. 

5.4.6.1 Write a Monitor Character Packet to Monitor Chain 

The interrupt routine writes a character to the monitor chain with this 
service. If the chain is empty, the character is written to the final buffer 
and the notification routine is called in interrupt context. Otherwise, the 
first monitor in the chain is activated in its process context. When it runs, 
it reads data from the chain and processes the character. The monitor 
thread then writes the processed character back to the chain, causing 
activation of the next monitor in the chain. When the last monitor writes 
back its character, the final buffer is filled with the processed character, 
and the notification routine is called in the context of the monitor 
controlling thread (ring 0). 

The data written to the monitor chain is first enclosed in a packet 
defined by the device driver. The header of this packet is defined by the 
monitor dispatcher, and is one word long. This word should be set to 0 
before the MonWrite service is issued to write a character data packet. 
The low order byte of the monitor word may take the values 1 or 2 to 
represent the monitor open and close functions to the monitor chain. 

USAGE: 

MOV SI, OFFSET DATAPACKET Place the address of the 

monitor character packet 
into DS:SI. The first word 
of this packet is used by 
the monitor dispatcher. 

The character packet must 
reside in the main data 
segment. 


MOV CX,PACKETSIEE 


size of monitor character 
packet is placed in CX 
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The handle for the chain 
to which the monitor char¬ 
acter packet is to be writ¬ 
ten is placed in AX. This 
handle was returned by 
Monitor Create. 

1 means return with error 
if buffer space is not imme¬ 
diately available. The in¬ 
terrupt service routine 
cannot wait for buffer 
space to become available. 

code for MonWrite 

address of device helper in¬ 
terface, extracted from 
Init I/O packet 

error return 

Character packet has been written to monitor 
chain and will be processed through all monitor 
threads on the chain before being written to the 
final buffer and processed by the notification 
routine. 

ERROR: 

AX contains the error code. Two error codes are 
defined: 

"Invalid Monitor Handle." 

"Not Enough Memory." 

The "Not Enough Memory" error occurs if the 
buffer is full, or if a MonFlush request is pending. 


MOV AX,CHAINHANDLE 

MOV DH, 1 

MOV DL,22h 

CALL DWORD PTR [DevHlp] 

JC ERROR 


5.4.7 Getting OS/2 Internal Variables at Interrupt Time 

At interrupt time, only the global INFO segment, the COM port words, 
and the reboot vector are valid. 
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5.4.7.1 Return Pointer to DOS Variable (GetDosVar, 24h) 

Each OS/2 internal variable is associated with a unique and bi-modal 
address. This address is returned for a particular variable with GetDos¬ 
Var. The address may then be used in the strategy mode, or in any other 
mode within the device driver. The available variable codes are listed in 
Table 5-6. 


Table 5-6: OS/2 Internal Variables _ 

CODE DESCRIPTION 

1 Address of a word containing the bi-modal segment address of 

the global INFO segment. The global INFO segment contains 
the current date and time, the current screen group, and other 
miscellaneous data. The global INFO segment is described fur¬ 
ther in the appendices. 

3 Address of the two COM port words. The first word contains 

the COM1 port address or 0 if COM1 is owned, and the second 
word 0 if COM2 is owned. 

5 Address of the offset, segment address of the OS/2 reboot vec¬ 

tor. A JMP to this address will cause cold reboot of the operat¬ 
ing system. 


USAGE: 


MOV AL,VarCode Place the variable code of 

the variable whose ad¬ 
dress is required in AL. 

The variable code is 
drawn from the above 
table. 

MOV DL,24h 

Code for DosGetVar. 

CALL DWORD PTR [DevHlp] address of device helper in¬ 

terface, extracted from 
Init 110 packet 


JC ERROR 
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The address of the variable is returned in AX:BX, 
AX containing the segment/selector, and BX con¬ 
taining the offset. 

ERROR: 

Variable code does not correspond to an OS/2 vari¬ 
able. 


5.4.8 Device Driver Communication Interrupt Time 

A link may be established between two device drivers, which we will term 
the source and target device drivers. The source device driver will call the 
target device driver. 

The source driver determines if it is functioning in real or protect mode, 
sets registers accordingly, and calls the target driver with a FAR CALL. 
Code and data segment register values are returned from the AttachDD 
DevHlp service, which is called in strategy or initialize context. The target 
driver is responsible for interpretation and/or saving of registers, and 
terminating with a far return. The format of the IDC data structure 
returned from AttachDD is depicted in Table 5-7. 


Table 5-7: IDC Data Structure 


OFFSET 

LENGTH 

DESCRIPTION 

0 

WORD 

Offset of IDC entry point 

2 

WORD 

Real-mode CS of IDC driver. 

4 

WORD 

Real-mode DS of IDC 

6 

WORD 

Offset of IDC entry point. 

8 

WORD 

Protect-mode CS of IDC driver 

OAh 

WORD 

Protect-mode DS of IDC driver 


5.4.9 Interrupt Management Helper Services 

The interrupt routine is entered due to an IRQ request from a controller 
issued to the PIC. The interrupt service routine is expected to service the 
controller and then dismiss the request at the PIC. The interrupt service 
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routine must consider the possibility of a nested interrupt after clearing 
the PIC. 

Normally, all interrupt vector management will take place at initializa¬ 
tion time. However, elimination of hardware interrupt service routines 
may be performed by the strategy routine. 

5.4.9.1 Clearing an Interrupt Level of the Interrupt Controller 

The EOI device helper routine issues an End-of-Interrupt (EOI31 h) to a 
master/slave 8259 interrupt controller. The interrupt level for which the 
EOI is issued is now active, and will generate an interrupt when re¬ 
quested by a device controller. If the EOI is issued for an IRQ level and a 
device controller is requesting an interrupt, the interrupt will immedi¬ 
ately occur. If the interrupt originates from the requesting controller, a 
nested interrupt takes place. Nested interrupts cause increased stack 
usage, an issue that must be carefully considered before the EOI is issued. 

Nested interrupts are postponed by clearing the interrupt flag—disa¬ 
bling all interrupts. The processor instruction CLI is used to clear this 
flag. 


USAGE: 


MOV AL,IRQnum 

number of interrupt level 
to be cleared (O-OFh) 

MOV DL,31h 

code for EOI 

CALL DWORD PTR [DevHlp] 

address of device helper in¬ 
terface, extracted from 

Init HO packet 


JC ERROR 

Here the IRQ level has been intercepted by the 
driver. 

ERROR: 

Register AX contains the error code. Currently 
defined code is "IRQ level not available." 
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5.4.9.2 Remove Hardware Interrupt Handler (UnSetIRQ, lCh) 

If a hardware interrupt (IRQ) is not needed after interrupt time (unusual 
case), the interrupt service routine may issue UnSetIRQ for that IRQ 
level. 


USAGE: 


MOV BX,IRQnum 

hardware interrupt level 
(0 - OFh) of interrupt to be 
removed) 

MOV DL,lCh 

code for UnSetIRQ 

DS must contain device driver data segment 
value before this call. 


CALL DWORD PTR [DevHlp] 

address of device helper in 
terface, extracted from 

Init 110 packet 


JC ERROR 

Here the interrupt routine has been removed. 
ERROR: 

Register AX contains the error code. Currently 
defined code is "IRQ level not owned by device 
driver." 




CHAPTER 6 


IMPLEMENTATION STRATEGIES 


6.1 Overview 

The device driver writer must integrate the design considerations out¬ 
lined in the previous chapters with the concerns of the functional exten¬ 
sion to be made to the operating system. This chapter will discuss 
separately the issues of adding a conventional interrupt-driver device to 
the operating system, and of extending the operating system in general. 

The primary problem raised in adding a new device to the operating 
system is maintaining coordination between strategy requests and the 
interrupt service routine. Three general techniques will be discussed— 
"strategy only," "single interrupt," and "nested interrupt." Flowcharts are 
included to illustrate the main concepts. Once the general problem of 
thread coordination with asynchronous' interrupting events is under¬ 
stood, it becomes easier to add more complex features to the basic model. 

The strategy only technique represents the simplest means of coor¬ 
dination between the strategy routine and the interrupt routine. The 
strategy routine is single-threaded, so that only one I/O request is pending 
at any time. The strategy routine starts I/O at the device and then blocks 
until the interrupt routine has finished servicing the I/O request. The 
strategy routine is then unblocked, releasing the semaphore and starting 
the next I/O request. 


307 
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Unfortunately, the simplistic structure of strategy only drivers does not 
make optimal use of the device controller. Once a particular I/O request 
is satisfied, the controller is idled until the strategy routine representing 
the next I/O request runs. Since strategy routines are prioritized and 
non-interruptible, it may take an indeterminate amount of time before 
the controller is started. The strategy only technique can be modified in 
order to start a waiting request while still in the interrupt service routine, 
thus creating the single interrupt method. 

The single interrupt driver has slightly more concurrence built into the 
strategy routine. The strategy routine determines if the device is busy, 
and blocks if it is. The interrupt routine will awaken the next waiting 
strategy packet when it completes the current I/O request. If the strategy 
routine determines that the device is idle, it marks the device as busy and 
starts device I/O. The interrupt routine will complete the I/O for this 
packet and mark its completion status. 

The single interrupt service routine is responsible for processing the 
condition at the controller that caused the interrupt request, and then for 
determining if the pending I/O request is complete. If the pending request 
is not complete, the interrupt is dismissed. 

If the pending I/O request is complete, the interrupt service routine 
sets completion status in the packet and retrieves the next waiting 
request packet. If there is no packet waiting, the device is marked idle; if 
a packet is waiting, the interrupt service routine starts I/O at the control¬ 
ler for the request. 

The single interrupt technique increases controller utilization by ser¬ 
vicing a waiting strategy packet in the interrupt service routine. The 
controller does not wait for a strategy routine to be scheduled. Careful 
examination of the strategy only technique will show that two strategy 
routines must be scheduled: one to complete the request, and one to start 
the next request. The price paid for the controller’s increased usage is 
complexity of implementation, as division of responsibility between 
strategy routine and interrupt service routine becomes blurred. 

The single interrupt technique is adequate for most simple device 
drivers, but runs into controller overrun difficulties for certain devices. 
For example, a serial device controller might receive characters at a 
demanding rate. On receipt of a special character, or a predetermined 
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number of characters, the interrupt service routine might be required to 
perform extensive processing (i.e., computation of a checksum) before 
posting completion status to the pending strategy packet. During this 
period, additional characters might be received by the device controller. 
If the controller lacks buffering capability, characters might be lost. 

The third device driver design algorithm is nested interrupt, where 
the interrupt service routine may itself be interrupted by a subsequent 
controller interrupt request. Here, paths through the interrupt service 
routine become highly parallel, and debugging the driver can become an 
extremely difficult task. The actual details of implementation will address 
the issue of device overrun for a model, but certain generalizations can 
be made. 

The interrupt service routine places data extracted from the device in 
a queue, and reenables controller interrupts. The interrupt routine then 
processes the data in the queue. 

If a device interrupt occurs, a second path is taken through the inter¬ 
rupt service routine which extracts data from the device and adds it to 
the data in the queue, reenables controller interrupts, and returns. The 
original interrupt service routine resumes processing of data. The first- 
level interrupt routine will handle strategy packet management and will 
terminate only after all data has been removed from the queue. 

Following presentation of flow charts and in-depth discussion of the 
three interrupt handling techniques, this chapter will discuss three 
sample device drivers: PIPER, TIMDMP, and RAMDRV. 

The PIPER driver constructs a pipe between two processes. Data is 
written to the driver PIPEIN$, and is buffered in an internal queue. A 
second process reads from the driver PIPEOUT$. When the PIPEIN$ 
driver is closed, the end-of-file condition is transmitted to the process 
reading from PIPEOUT$. This driver is a good example of process coor¬ 
dination within a device driver, and also of coordination of open and close 
logic without file manager support. 

The TIMDMP driver allows a process to specify a range of absolute 
memory addresses to be dumped. The device driver suspends for a period 
and then returns the data to the calling process. The purpose of the timed 
suspension is to illustrate coordination between strategy and interrupt 
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contexts, and to illustrate memory addressability in interrupt context. 
The driver also features the use of generic IOCtl calls. 

The RAMDRV driver is a sample RAM-disk driver, which simulates 
the architecture of a block device driver. This driver can be used to 
understand and prototype block device drivers, and features FORMAT 
program and full file manager support. RAMDRV makes an inter-device 
call to driver STRAT$, which records the sequence of strategy packets 
received by the RAMDRV driver. These packets may then be examined 
by the reader. 

6.2 Strategy Only Driver Algorithm 

On receipt of a READ or WRITE request packet, the strategy routine 
requests a semaphore, forcing serialization of the requests. Only one 
request will run at a time, and it will release the semaphore immediately 
before returning to the kernel. 

When the strategy routine obtains the semaphore, it will start the I/O 
request and store the tiled address of the request packet into the main 
data segment. The strategy routine disables interrupts before starting 
the device to avoid the possibility of the device interrupt occurring before 
the strategy routine has time to block, resulting in the permanent block¬ 
ing of the strategy routine. Similarly, the address of the request packet is 
stored into the main data segment (address CURRPACKET) while inter¬ 
rupts are disabled because the interrupt service routine will clear this 
address. In general, any access by the strategy routine to the device 
controller or to data areas that will be addressed by the interrupt service 
routine, must be preceded by disabling interrupts in order to avoid conflict 
between the routines (see the accompanying flowchart). 

Once the device I/O has been started and CURRPACKET set to the 
address of the request packet, the strategy routine blocks. No further 
action should take place until the interrupt service routine completes. 
When the interrupt routine decides the request has been satisfied, it will 
clear CURRPACKET and run the strategy routine blocked on the packet 
address. When the strategy routine awakens, it must determine if it has 
been inadvertently awakened by another routine by checking the con¬ 
tents of CURRPACKET for 0. 
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Flowchart 6.2 
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Because of the rule about sharing data structures with the interrupt 
routine, the strategy routine disables interrupts, checks CURRPACKET 
for 0, and—if CURRPACKET is not 0— blocks again to wait for completion 
of the request by the interrupt service routine. 

When the strategy routine unblocks following the interrupt service 
routine, interrupts are enabled and the semaphore is released. Interrupts 
are enabled because the semaphore is accessed only in strategy context 
so interrupt service routine will not interfere with the logic flow. When 
the semaphore is cleared, the thread representing the next READ or 
WRITE request waiting at the semaphore is scheduled. The strategy 
routine then terminates with a FAR return. 

The interrupt service routine is entered in response to a controller 
interrupt request. It immediately enables interrupts, allowing interrupt 
requests from higher-priority devices to be serviced. Interrupts from the 
same or lower priority devices are disabled by the PIC. 

DS is set by the interrupt manager to the address of the main data 
segment. This allows the interrupt service routine to recover the address 
of the strategy packet from CURRPACKET. The interrupt routine per¬ 
forms I/O to the device controller. If this interrupt completes the I/O 
request, the interrupt service routine sets the I/O completion status in 
the request packet, clears CURRPACKET to indicate to the strategy 
routine that the I/O is complete, and runs the strategy routine. 

In any event, the interrupt service routine now disables interrupts to 
prevent nested interrupts from the same device, and enables interrupts 
for the controller at the PIC with the EOI DevHlp service. Finally, the 
interrupt service routine clears the carry bit of the processor status word 
to indicate to the interrupt manager that the interrupt was serviced, and 
returns to the interrupt manager. 

6.3 Single Interrupt Driver Algorithm 

The single interrupt algorithm charges the interrupt service routine with 
the responsibility to start waiting I/O requests. This means the strategy 
routine must make these packets available to both the interrupt service 
routine and the strategy routine. 
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Flowchart 6.3 
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This makes the semaphore an inappropriate mechanism for serialization, 
and adds somewhat to the complexity of the strategy routine (see the 
flowchart). 

On receipt of a READ or WRITE request, the strategy routine clears 
the status word of the strategy packet header. This field will be used later 
by the interrupt service routine to indicate completion of the I/O request. 
This operation takes place with interrupts enabled because the address 
of the strategy packet is not yet available to the interrupt service routine. 
The strategy routine then disables interrupts in order to examine and 
modify structures that are shared with the interrupt service routine. 

The strategy routine then tests the CURRPACKET field. If CUR- 
RPACKET is zero, the device is idle. The strategy routine sets CUR¬ 
RPACKET to the address of the strategy packet, and starts device I/O. 
The strategy routine then blocks. If the device was busy, then the strategy 
routine would push the strategy packet address onto a request queue, and 
block. 

When the strategy routine unblocks, it must determine if it was 
awakened by I/O completion or erroneously by another routine. The 
strategy routine disables interrupts, and tests the DONE bit of the status 
word of the strategy packet header. If the DONE bit is clear, the strategy 
routine was awakened erroneously and the strategy routine blocks. If the 
DONE bit is set, the strategy routine performs a FAR return to terminate. 

The interrupt service routine will be invoked when the processor 
acknowledges an interrupt request from the PIC. The interrupt manager 
will save all registers, set DS to point to the current main data segment, 
and perform a FAR CALL to the interrupt service routine. 

The interrupt service routine should enable interrupts; this will allow 
devices with higher PIC priority than the device that caused the interrupt 
to be serviced. The interrupt routine then retrieves the address of the 
strategy packet representing the current I/O request from CURRPACK¬ 
ET. 

The interrupt routine then performs the required I/O to the device 
controller. If this action completes the I/O request, the interrupt service 
routine will set the status of the current packet, and then start the next 
waiting I/O request. 
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The completion status of the current I/O request is set in the status 
word of the current packet, and the strategy routine is scheduled with the 
Run helper service. The strategy routine will then run to completion. 

The interrupt routine then pulls the next strategy packet from the 
request queue. If no packet is waiting, the driver sets CURRPACKET to 
0, marking the device as idle. If a strategy packet was waiting, its address 
is placed in CURRPACKET, and the interrupt service routine starts 
device I/O. 

The in terrupt service routine terminates by disabling interrupts to 
prevent nested interrupts from the same device, and issuing the helper 
request EOI to reenable interrupt requests at the PIC from the device. 
The interrupt routine then clears the carry flag to indicate to the interrupt 
manager that it has serviced the interrupt, and performs a EAR return. 

If the strategy routine performs no additional processing after it blocks, 
a slightly simpler routine may be coded. The strategy routine may return 
instead of blocking, and will instead be blocked by the kernel. The 
interrupt service routine would then issue the helper service DevDone 
instead of Run. The kernel then has responsibility of verifying correct 
wakeup and of returning completion status to the file manager. 

6.4 Nested Interrupt Driver Algorithm 

The nested interrupt algorithm is illustrated for demonstration purposes 
only, and should not be used as template for an actual device driver. The 
details of this algorithm are sensitive to the nature of the device controller 
itself and will have to be modified to support a particular device properly. 
The de sign issues involved, however, are illustrated by the accompanying 
flowcharts. 

For the purposes of this demonstration, the model of the device control¬ 
ler was taken to be a character-oriented device that inputs characters 
from the controller. Receipt of each character generates an interrupt. The 
device driver is expected to buffer characters received before a READ 
request. The nested interrupt algorithm uses the same strategy 
philosophy as the single interrupt algorithm in that the strategy routine 
primarily queues strategy packets for later manipulation by the interrupt 
service routine. 
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On receipt of a READ request, the strategy routine clears the status 
word of the request packet header. The interrupt service routine will set 
the status word to indicate I/O completion to the strategy routine. The 
strategy packet is not yet addressable by the interrupt service routine, so 
the status word is cleared without interrupt protection. The contents of 
the variable READPACKET are then tested for 0. Value 0 in READPACK- 
ET is taken to mean no READ request is pending, and so this strategy 
routine gains immediate control. This field is also altered by the interrupt 
service routine, and must be protected against interruption while making 
the test. 

If READPACKET is not zero, a strategy packet is currently being 
serviced. This packet is then pushed on the request queue (READQ), and 
the strategy routine blocks. Interrupts must remain disabled throughout 
this process. The decision must be protected because the contents of 
READPACKET might be changed by the interrupt service routine. The 
action of pushing the request packet must be done while interrupts are 
disabled to prevent the possibility that the interrupt routine might 
complete the pending I/O request while the current request is being 
queued (resulting in a deadlock or a damaged queue). Finally, the block 
must be protected against the possibility of the interrupt routine attempt¬ 
ing to run the thread before it is blocked, resulting in a thread which will 
never awaken. 

A zero value in READPACKET means that the strategy routine has 
gained control of the device. The strategy routine places the strategy 
packet address in READPACKET to indicate that I/O is being performed 
to this packet. The strategy routine sets STRATFLAG to 1 to indicate to 
the interrupt service routine that the strategy routine is handling I/O 
from the character queue until the character queue is emptied, or until 
the READ request is satisfied. The strategy routine then attempts to 
service the READ request with data from the character queue. 

The strategy routine reads a character from the character queue. If the 
character queue was empty, the strategy routine clears STRATFLAG and 
blocks. The sequence of checking the character queue through blocking 
the strategy routine must be protected by disabling interrupts. The block 
must take place in the same critical section as the queue check. If it doesn’t 
the interrupt service routine could receive characters and fail to service 
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the READ request (if STRATFLAG=1), or it could service the READ 
request and attempt to run the thread before it is blocked, resulting in a 
permanent sleep for the thread (if STRATFLAG=0). 

If a character was present in the character queue, the driver enables 
interrupts and services the READ request with that character. If addi¬ 
tional characters are needed to service the request, the strategy routine 
disables interrupts to recheck the character queue. Servicing the request 
is not critical because the interrupt routine will check STRATFLAG 
before doing so, thereby protecting this code from interference while 
allowing the character queue to receive additional characters from the 
device. 

If the READ request has been serviced, the strategy routine clears 
READPACKET (indicating that no READ request is pending), clears 
STRATFLAG to indicate to the interrupt service routine that it may now 
service pending READ requests, sets the completion status in the status 
field of the strategy packet header, and returns to the kernel. This path 
does not require interrupts to be disabled. If the interrupt service routine 
is called before READPACKET is cleared, the routine will not service the 
strategy packet because STRATFLAG is still 1. If an interrupt occurs after 
STRATFLAG is set to 0, the interrupt service routine will not service the 
strategy packet because READPACKET will be 0. Careful analysis of each 
path through the strategy routine is very typical of device driver design. 

When the strategy routine unblocks, it returns an error status in case 
of unusual wakeup. In the event of a normal wakeup, the strategy routine 
disables interrupts and tests the DONE bit of the strategy packet header’s 
status word. If the, DONE bit is clear, the strategy routine was awakened 
erroneously, and the strategy routine blocks. If the DONE bit is set, the 
strategy routine may enable interrupts, and performs a FAR return to 
terminate. 

The interrupt service routine will be invoked when the processor 
acknowledges an interrupt request from the PIC. The interrupt manager 
will save all registers, set DS to point to the current main data segment, 
and perform a FAR CALL to the interrupt service routine. 

The interrupt service routine enables interrupts, which allows devices 
of higher priority to interrupt the current routine. The device which 
caused this interrupt routine to be entered, and all lower-priority devices, 
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will have their interrupt requests postponed at the PIC until the interrupt 
service routine issues the helper service EOI. 

The interrupt service routine gets the character from the device and 
adds the character to the ReadCharQueue. The interrupt service routine 
then adds 1 to NESTCT, and determines the current nesting level. 
Internal logic in the nesting routine LEVEL2 prohibits additional nest¬ 
ing. 

At LEVEL1, nested interrupts are enabled at the PIC with EOI. 
STRATFLAG is tested to determine if the strategy routine is servicing 
the READ request. If it is, the interrupt service routine disables inter¬ 
rupts to protect its return path from reentry, decrements NESTCT, clears 
the Carry bit (to indicate to the interrupt manager that the interrupt has 
been serviced), and returns to the interrupt manager. 

If the interrupt service routine is responsible for handling the READ 
request (STRATFLAG is 0), the interrupt service routine disables inter¬ 
rupts to get the next character waiting in the ReadCharQueue and tests 
the queue for empty. If the queue is empty, the interrupt service routine 
returns through the path described above. 

If a character was waiting in the queue, the READ strategy packet is 
to be serviced with the character. This is done with interrupts enabled, 
allowing nested interrupts to continue adding characters to the queue 
even if the process of servicing the READ request involves extensive 
processing. The interrupt service routine then determines if the READ 
request has been satisfied. If additional characters are needed to service 
the request packet, the interrupt service routine loops to get the next 
character waiting on ReadCharQueue. 

If processing for the READ request is complete, the interrupt service 
routine sets completion status in the strategy packet and unblocks the 
READ strategy routine. The interrupt routine then pulls the next waiting 
READ request from READQ. If READQ was empty, READPACKET is set 
to 0, indicating the device is idle and the interrupt service routine returns. 
If a READ request was waiting on READQ, the interrupt routine places 
its address in READPACKET, and starts service of the packet by looping 
to get a character from ReadCharQueue. 

The LEVEL2 code simply returns to the interrupt manager, having 
already queued the character from the controller to ReadCharQueue. 
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NESTCT is decremented and then interrupts are disabled before issuing 
EOI. This prevents nesting of the LEVEL2 interrupt service routine. 
Carry is cleared to indicate service of the interrupt, and a FAR return is 
performed to the interrupt manager. 

6.5 PIPER 

PIPER.SYS is a device driver module composed of two drivers: PIPEIN$ 
and PIPEOUT$. These drivers communicate to form a pipe between two 
processes, a writer process and a reader process. The writer opens 
PIPEIN$, writes a character stream, and closes PIPEIN$. The reader 
opens PIPEOUT$, reads a fixed character count or until end-of-file, and 
closes PIPEOUT$. 

Process coordination includes blocking the writer if the pipe is full, 
blocking the reader if the pipe is empty, and returning end-of-file to the 
reader when the writer closes the pipe. The pipe is not available to another 
writer until the reader reads end-of-file or closes the pipe, and writer 
processes wait until the pipe is available. Reader processes wait until the 
current reader closes the pipe. A writer may write to several reader 
processes, if the readers do not expect end-of-file. In order to correctly 
generate the end-of-file condition, a reader may read from multiple 
writers only by reading past the end-of-file condition. 

6.5.1 PIPEIN$ 

PIPEIN$ is opened by a process for output, and characters are written to 
PIPEIN$. PIPEIN$ buffers characters received from the thread until the 
internal buffers are full, at which time PIPEIN$ blocks. PIPEIN$ remains 
owned by the writing process until the process closes the connection to 
the driver. The driver will not be available to be opened by another process 
until its internal buffers have been cleared. 

6.5.1.1 Initialize At initialize time, PIPEIN$ is responsible for only 
conventional initialize-time operations for character devices. PIPEIN$ 
obtains and saves the device helper entry point, and places the length of 
the main code and main data segments into the INIT packet. The driver 
then initializes its internal character queue, initializes all internal vari- 
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ables, and writes a signon message to the screen. Finally, the driver sets 
completion status in the INIT packet and returns. 

6.5.1.2 Open Logic At open time, PIPEIN$ must check to see if a close 
to PIPEIN$ is "incomplete," i.e., a previous writer has closed the pipe but: 

• The buffer is not empty, or 

• The reader that cleared the buffer has not read EOF and 

• The reader that emptied the buffer has not closed 

If PIPEIN$ is in a close incomplete state, the strategy packet is placed 
on the PIPEIN$ Open Queue, and the strategy thread blocks. 

When a thread on the PIPEIN$ Open Queue awakens, it checks for 
unusual wakeup (process death), and returns an error code if so. The 
thread then checks for accidental wakeup, and returns to the blocked 
state if it was accidentally awakened. If not, the thread was awakened by 
satisfaction of the close incomplete state, which takes place when the 
reader reads the end-of-file condition, or closes after clearing the internal 
character buffer. At satisfaction of the close incomplete state, all strategy 
packets are dequeued from the PIPEIN$ Open Queue, so that the highest- 
priority thread will enter the strategy routine first and gain ownership 
of the pipe. 

If an OPEN request occurs when PIPEIN$ is not in the close incomplete 
state, the strategy routine gets its process ID from the local INFO 
segment, and determines if PIPEIN$ is owned by any process. If not 
owned, the strategy routine marks PIPEIN$ as being owned by itself, sets 
completion status, and returns. If PIPEIN$ was already owned by this 
process, the strategy routine increments the PIPEIN$ Open Counter to 
keep track of the number of open requests from this process, sets comple¬ 
tion status, and returns. 

If PIPEIN$ is owned by another process, the strategy packets is added 
to the PIPEIN$ Open Queue, and will block until the current owner 
closes—its close request is completed by a reader. 

6.5.1.3 Write Logic On entry, the strategy routine determines its 
process ID from the local INFO segment, and checks if it owns PIPEIN$. 










324 


WRITING OS/2 DEVICE DRIVERS 


Flowchart 6.5.1.2 
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Since the OPEN request will not succeed until PIPEIN$ is owned, this 
check is redundant for well-behaved applications. Once the strategy 
routine has determined it owns PIPEIN$, it attempts to obtain the Write 
Semaphore. If another WRITE request is pending, the strategy routine 
will block until the previous request is satisfied. When the strategy 
routine awakens, it checks for unusual wakeup and returns error status 
if this was the case. The buffer address in which the data to be written is 
obt ain ed, and is mapped to a virtual address for the transfer. If the map 
fails, an error condition is returned. 

The strategy routine counts the number of characters it has written to 
the character queue using variable WRCTR. WRBLCTR is used to count 
the n umb er of characters written between successive blocks of the WRITE 
routine. 

While characters are left in the WRITE buffer, the strategy routine gets 
the next character and writes it to the character queue. If the character 
queue accepts the character, WRCTR and WRBLCTR are incremented 
and the strategy routine loops while characters remain in the WRITE 
buffer. 

If the character queue refuses the character, the queue is full. Variable 
WRBLCTR is tested to see if any characters were written to the queue. 
If any characters were written to the queue, the PIPEOUT$ variable, 
RDPKTID is tested to determine if a READ request to PIPEOUT$ is 
pending. If a READ request is waiting, it is unblocked so it can read the 
contents of the character queue, eventually causing this WRITE thread 
to continue. The PIPEIN$ WRITE thread then blocks, setting WRPKTID 
to the strategy packet address (so the PIPEOUT$ READ routine can 
restart this routine), and clearing WRBLCTR. When the WRITE routine 
awakens, it returns error status for unusual wakeup, or returns to the 
character transfer routine. 

When the WRITE buffer has been emptied, the strategy routine clears 
the Write Semaphore, allowing the next waiting WRITE request to be 
scheduled. If the reader is blocked (RDPKTID not 0), the WRITE strategy 
routine unblocks the reader. The WRITE routine then sets completion 
status, and returns. 
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6.5.1.4 Read Logic Read requests to PIPEIN$ are not permitted. 
Error status is set and the routine returns. The error code that is returned 
is based on whether or not the pipe is owned by the requesting process. 

6.5.1.5 Close Logic At entry to the CLOSE routine, the strategy 
routine determines if PIPEIN$ is owned by the process issuing the 
CLOSE request. If the requesting process is not the owner, an error status 
is returned. The strategy routine obtains the Write Semaphore. This is to 
serialize the CLOSE request with any pending WRITE requests, so a 
CLOSE request will not be serviced if a WRITE request is incomplete. 

The PIPEIN$ Open Count is decremented and, if not 0, returns com¬ 
pletion status. When the Open Count becomes 0, PIPEIN$ enters the close 
pending state—unless the character queue is empty, and PIPEOUT$ is 
not open, in which event all strategy packets on the PIPEIN$ Open Queue 
are unblocked. If PIPEIN$ entered the close pending state, it checks 
RDPKTID to see if the reader is waiting and unblocks the reader. In either 
case, the strategy routine returns completion status. 

6.5.2 PIPEOUT$ 

PIPEOUT$ is opened by a process for input. When a read request is issued 
to PIPEOUT$, the contents of the internal character buffer are returned 
and the buffer is emptied. If the buffer is empty, the driver blocks until 
characters are written to PIPEIN$. If the process which owns PIPEIN$ 
closes, PIPEOUT$ will return a character count of 0 to a read request 
once the internal buffer has been emptied. This causes the process to 
receive an end-of-file condition. 

6.5.2.1 Initialize Logic At initialize time, PIPEOUT$ is responsible 
only for conventional initialize-time operations for character devices. 
PIPEOUT$ places the length of the main code and main data segments 
into the INIT packet. The driver then initializes all internal variables and 
writes a sign on message to the screen. The device helper address and the 
character queue have already been initialized by PIPEIN$. Finally, the 
driver sets completion status in the INIT packet and returns. 
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6.5.2.2 Open Logic The OPEN strategy routine determines its 
process ID from the local INFO segment. If PIPEOUT$ is not owned, the 
strategy routine establishes ownership. If PIPEOUT$ is owned by this 
process, PIPEOUT$ Open Counter is incremented to tally the number of 
OPEN requests from this process. If PIPEOUT$ is owned by another 
process, the strategy packet is placed on the PIPEOUT$ Open Queue and 
the strategy routine blocks. When the owning process releases 
PIPEOUT$, all waiting OPEN requests will be unblocked. This will cause 
the highest-priority thread to gain ownership of PIPEOUT$. 

When the thread awakens, it checks for unusual wakeup and sets 
appropriate error status if so. If not, the strategy routine checks for 
accidental wakeup and blocks in this case; otherwise, the strategy routine 
attempts to open PIPEOUT$. 

6.5.2.3 Read Logic The READ strategy routine determines its process 
ID from the local INFO segment. If PIPEOUT$ is not owned by this 
process, error status is returned. The strategy routine then obtains the 
Read Semaphore. If another READ request is pending, this strategy 
routine will block until the previous READ is satisfied. When the strategy 
routine awakens, it returns error status in case of unusual wakeup. If the 
READ strategy routine has obtained the semaphore, it maps the I/O 
buffer to a virtual address in order to perform the transfer. 

The strategy routine then attempts to read a character from the 
character queue. Each character read from the character queue is placed 
in the I/O buffer. If the read has been satisfied (at least as many charac¬ 
ters were in the queue as the count contained in the READ packet), the 
strategy routine determines if the writer is blocked by checking 
WRPKTID. If the writer was blocked, it is unblocked. 

The Read Semaphore is released, allowing the next READ request to 
start, and completion status is returned. If the character queue is empty 
before the READ request is satisfied, the strategy routine determines if 
any characters have been transferred. If any characters have been read, 
the character count is set in the I/O packet to the number of characters 
transferred and the READ request is considered satisfied. 
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Flowchart 6.5.2.2 
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Flowchart 6.5.2.3 
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The strategy routine determines if the writer is blocked by checking 
WRPKTID, and unblocks the writer. The Read Semaphore is released, 
allowing the next READ request to start, and completion status is 
returned. 

If no characters were transferred, the strategy routine checks if 
PIPEIN$ is in the close pending state. If not, the reader blocks until 
characters have been written to the character queue. When the strategy 
routine awakens, it returns error status for unusual wakeup. If properly 
awakened, the strategy routine attempts to transfer characters from the 
character queue. If the queue is still empty, the reader has been awakened 
accidentally, and will return to the block. 

If PIPEIN$ was in the close pending state, the empty character queue 
is believed to represent the end-of-file condition. The READ packet I/O 
character count is set to 0, which represents EOF. PIPEIN$ is reset to the 
unowned state, and all OPEN packets on the PIPEIN$ Open Queue are 
unblocked (so the highest-priority thread will obtain ownership of 
PIPEIN$). When all PIPEIN$ OPEN threads have been Run, the Read 
Semaphore is released, allowing the next READ request to start, and 
completion status is returned. 

6.5.2.4 Write Logic Write requests to PIPEOUT$ are not permitted. 
Error status is set and the routine returns. The error code that is returned 
is based on whether the pipe is owned by the requesting process. 

6.5.2.5 Close Logic The CLOSE strategy routine obtains its process 
ID from the local INFO segment. If the process is not the current owner, 
error status is returned. The strategy routine then obtains the Read 
Semaphore, serializing the CLOSE request with any READ requests. 
This prevents a CLOSE request from being serviced while a READ 
request is incomplete. 

The strategy routine releases the semaphore and decrements the 
PIPEOUT$ Open Counter. If the PIPEOUT$ Open Count is not 0, com¬ 
pletion status is returned. 
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Flowchart 6.5.2.4 
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Flowchart 6.5.2.5A 


6.5.2.5 - CLOSE 
PIPEOUTS - 
CLOSE LOGIC 
WITH DEQUEUE 
(PAGE 2 OF 



NO / Is Write 

-H Close 

N. Pending? 


Attempt to 
Pull Packet 
from PIPEINS 
Open Queue 



RETF 


Run Blocked 
Thread 












340 WRITING OS/2 DEVICE DRIVERS 


If the PIPEOUT$ Open Count is 0, the PIPEOUT$ device is set 
unowned. If PIPEIN$ is in the close pending state, the strategy routine 
clears the close pending flag and runs all OPEN strategy packets on the 
PIPEIN$ Open Queue. The PIPEIN$ device will be owned by the highest- 
priority waiting thread. 

The strategy routine then unblocks all threads on the PIPEOUT$ Open 
Queue. The highest-priority thread will own the PIPEOUT$ device. The 
CLOSE thread then returns completion status. 

6.5.3 Compile and Run 

The code for PIPER is contained in file PIPER.ASM. File PIPER.DEF 
contains the LINK command LIBRARY. File PIPER.CMD contains the 
MASM and LINK commands to produce the link module PIPER.SYS. The 
command DEVICE=PIPER.SYS, which installs the PIPIN$ and 
PIPEOUT$ drivers, should be added to file CONFIG.SYS. Listings of 
these files are included in Appendix F. 

6.6 TIMDMP 

TIMDMP.SYS is a single device driver, TIMDMP$. This driver accepts 
only the INIT strategy packet, and the category 80h, function 0 IOCtl 
"dump memory after time-out interval." The parameter buffer specified 
in the IOCtl packet contains a pause interval in seconds, and the address 
and length of physical memory to be copied into the data buffer. 

TIMDMP illustrates the interaction between strategy routine and 
interrupt routine. The strategy routine sets the timer handler to be called 
when the interval lapses, and blocks. The timer routine will map both the 
data buffer and a physical block of memory to be dumped, and copy the 
contents of the physical memory into the data buffer. The timer routine 
awakens the strategy routine and returns. The strategy routine will 
awaken, and run to completion. 

6.6.1 TIMDMP$ Initialize Routine 

Initialization requires the extraction of the helper service entry point’s 
address, and placement of the length of the main code and main data 
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se gm ents in the strategy packet. The INIT strategy routine also writes a 
startup message to the screen. 

6.6.2 TIMDMP$ IOCtl Strategy Routine 

On receipt of an IOCtl, the strategy routine verifies the category code of 
TDCATEGORY (80h), and function code TDFUNCTION (0). If either 
category or function is incorrect, the strategy routine returns with error. 

The strategy routine then checks CURRPACKET for 0, meaning the 
driver is idle. If the driver is busy, the request packet is added to STRATQ, 
and the strategy routine blocks. When the routine awakens, it loops to 
check CURRPACKET, to avoid the possibility of accidental awakening. 
This sequence of events is performed with interrupts disabled, to prevent 
interference from the timer routine. 

The strategy routine sets the address of the strategy packet into 
CURRPACKET to indicate ownership of the driver. The accessibility of 
the IOCtl Parameter Buffer and Data Buffer to the underlying process is 
checked, and an error is returned if either buffer is not accessible. The 
data buffer is then locked, and its lock handle is placed into the variable 
LOCKHANDLE. 

The clock tick interval in .1 milliseconds is extracted from the local 
INFO segment, and the pause interval specified in the Parameter Buffer 
is converted from seconds to .1 milliseconds through multiplication by 
10,000. The clock tick interval is divided into the pause interval, giving 
the pause interval in clock ticks. 

Variable PHYSICALADDRESS is set to the address of the physical 
block of memory to be dumped, and PHYSICALSIZE is set to the length 
of this memory block. The strategy routine sets a timer entry point 
(TIMERHANDLE) to be called after the pause interval. 

The strategy routine then blocks. On awakening, the strategy routine 
tests WAKEFLAG to determine if it has been accidentally awakened. If 
accidentally awakened, the strategy routine blocks. The strategy routine 
determines if any packets are waiting in the STRATQ. If so, a packet is 
removed from the queue and awakened. CURRPACKET is set to 0 to mark 
the driver available. Completion status is set in the strategy packet, and 
the strategy routine returns to the kernel. 
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Flowchart 6.6.2 
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6.6.3 TEMDMP$ Timer Handler 

The timer handler is called when the time-out interval is lapsed, and the 
dump operation is to commence. The timer entry point is called in an 
unpredictable context and it must be able to function regardless of 
underlying process context. 

The timer handler starts by mapping the physical buffer to be dumped 
to DS:SI. The timer handler then maps the IOCtl Data Buffer into which 
the physical buffer is to be copied into ES:DI. 

The tim er handler is known to be called in protect mode, but an actual 
interrupt service routine could be called in real mode. The timer handler 
tests for real/protect mode change in the mapping of the Data Buffer, and 
remaps the physical buffer if the mode has changed. This logic will never 
be used by the timer handler, but it is included for illustration. 

The contents of the physical buffer are copied to the Data Buffer. The 
mapping is then terminated. 

The timer handler is then removed from the system list of handlers, so 
it will not be called again. WAKEFLAG is set to 1, and the strategy routine 
whose packet address is in CURRPACKET is awakened. All registers are 
restored, and the timer routine returns. 

6.6.4 Compile and Run 

Test program DUMP.C is provided, with its .DEF file containing the LINK 
NAME command, which specifies that DUMP can run in a window under 
Presentation Manager. Program DUMP prompts the user for the address 
and length of the physical memory to be dumped, and the number of 
seconds for the time-out interval. DUMP then opens a handle to 
TIMDMP$ and issues the IOCtl to the driver. 

DUMP finally prints the contents of the physical buffer on the screen. 
FILE TIMDMP.CMD contains the CL and LINK commands to produce 
load module DUMP.EXE. The code for TIMDMP$ is contained in file 
TIMDMP.ASM. File TIMDMP.DEF contains the LINK command 
LIBRARY, required for device drivers. 
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Flowchart 6.6.3 
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File TIMDMP.CMD contains the MASM and LINK commands in order 
to produce the link module TIMDMP.SYS. The command 
DEVICE=TIMDMP.SYS, which installs the TIMDMP$ driver, should be 
added to file on CONFIG.SYS. Listings of these files will be found in 
Appendix G. 

6.7 RAMDRV 

RAMDRV is composed of a character device driver STRAT$, and a block 
device driver (RAMDRV.SYS). The character device driver is used to 
report the sequence of strategy packets issued to the RAM device driver, 
for the reader’s information. RAMDRV is a conventional RAM disk driver. 


6.7.1 The RAMDRV Driver 

When RAMDRV is loaded, it is assigned a logical unit number, which is 
translated into a one-character name for reference with the file system. 
The driver prints its name and the base address of the RAM it manages 
at initialize time, so the user may refer to the device or dump the contents 
of its memory. The driver also establishes the IDC link to STRAT$ at 
initialize time. 

After initialization, the RAM media is in an unformatted state, and 
expects to receive format requests. Program FORMAT.C is provided to do 
the formatting, as it is a device-independent format program. The sys¬ 
tem-provided format program contains code specific to the base-line disk 
driver, and cannot be used. 

Until formatting commands have been issued the device, the driver 
returns media changed status to the MEDIA CHECK command. This 
forces the file manager to read the FAT and root directory after the media 
format has been completed. 

The RAM driver supports the strategy packets INIT, MEDIA CHECK, 
BUILD BPB, REMOVABLE MEDIA, PARTITIONABLE FIXED DISKS, 
READ, and WRITE. The GENERIC IOCtl packets Get Parameters and 
Write Track are also supported. IOCtl packet Write Track is used by the 
format program. 
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6.7.1.1 Strategy Entry At entry to the RAMDRV strategy routine, the 
driver determines whether this is an INIT packet and jumps to the Init 
routine if so. Otherwise, the real/protect context of the driver is deter¬ 
mined by checking bit 0 of the MSW returned by the processor instruction 
smsw. 

In real mode, the real-mode CS and DS are established, and the 
STRAT$ IDC routine is called, which records the contents of the strategy 
packet contained in ES:DI. DS is then restored to the value for the 
RAMDRV driver, and a FAR CALL is made to the strategy routine, which 
processes the strategy packet. When the strategy routine returns, the 
real-mode CS and DS registers are reestablished, and a second call is 
made to the STRAT$ IDC routine. A FAR return is then issued to return 
to the kernel. 

In protect mode, the same sequence of setting registers for the IDC call, 
making the IDC call, setting DS for the strategy routine, calling the 
strategy routine, and resetting registers and making the IDC call is 
followed by the return to the kernel. STRAT$ now has a record of the 
strategy packet contents before and after calling the strategy routine. 

6.7.1.2 Init Strategy Routine The standard block device initializ ation 
actions are performed, followed by printing a startup message and attach¬ 
ing the STRAT$ IDC entry point. 

The address of the helper service routine is obtained from the INIT 
packet, and saved for later reference. The main code and main data 
segment lengths are placed into the INIT packet, as well as the number 
of logical units (1), and the address of the BPB array. There being only 
one unit, the BPB array is a single NEAR pointer to the BPB. 

Routine DosWrite is called to print a startup message. The startup 
message will display the block device unit name, and the physical base 
address of the RAM managed by RAMDRV. The unit name is used in 
conjunction with the file manager to reference the RAMDRV device. 

The base address of RAM is provided so the user may dump the contents 
of the driver using the DUMP facility of the TIMDMP system. 
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The AttachDD helper service is used to attach the STRAT$ device, 
which must have been loaded before the RAMDRV driver. STRAT$ 
records the contents of each strategy packet sent to the RAMDRV driver, 
and the contents of the strategy packet before the strategy routine returns 
to the kernel. The contents of the INIT packet are not recorded. 

6.7.1.3 BuildBPB Strategy Routine On receipt of the BUILD PBP 
strategy packet, the contents of the BPB are copied into the strategy 
packet. 


6.7.1.4 MediaCheck On receipt of the MEDIA CHECK packet, the 
strategy routine places the value in ChangeFlag into the packet. This 
value is initially OFFh, which causes the file manager to discard its 
internally buffered copies of the FAT and root directories. ChangeFlag 
will be reset to 1 after a FORMAT operation is followed by the RESET 
MEDIA command. 

6.7.1.5 ResetMedia The driver assumes a format operation is taking 
place when it receives a WriteTrack GENERIC IOCtl packet, and sets the 
ResetFlag to 1 to record this fact. The ChangeFlag will be set to 1 on 
receipt of the next RESET MEDIA packet. The effect of this logic is to 
force the file manager to read in new copies of the FAT and root directories 
after a format operation. 

6.7.1.6 Removable Strategy Routine Strategy routine Removable is 
called in response to the REMOVABLE MEDIA strategy packet. The 
driver sets the status word of the packet to indicate fixed media. 

6.7.1.7 Partitionable Strategy Routine When strategy packet PAR- 
TITIONABLE FIXED DISKS is received, the strategy routine returns the 
number of physical drives supported as 1. 

6.7.1.8 LogicalUnitMap Strategy Routine Alogical unit map indicat¬ 
ing a single unit is present on the physical drive is returned in the strategy 
packet. 
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Flowchart 6.7.1.7 


Flowchart 6.7.1.8 
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6.7.1.9 GenericIOCtl Strategy Routine If the Category code is not 8, 
error status is returned in the packet. If the Function code is neither 44h 
(Write Track) nor 63h (Get Device Parameters), an error status is 
returned in the packet. 

If the Function code is 44h, the routine JMPs to WriteTrk. If the 
Fu nc tion code is 63h, a JMP is made to GetParms. 

GetParms copies the BPB into the Data Buffer, and returns. 

WriteTrk sets ResetFlag to 1, indicating the format operation is 
complete. The media changed code will be sent to the next MEDIA 
CHECK packet to cause the file manager to read fresh copies of the FAT 
and root directory. 

The track of the transfer is computed as the starting cylinder of the 
transfer (WriteCylinder) times the number of tracks per cylinder (track- 
size) added to the track number within cylinder (WriteFirst) of the track, 
and is placed in AX:BX. The number of sectors to be transferred (Write- 
Count) is placed in CX. 

The tr ansf er offset in AX:BX and the transfer count in CX are converted 
from sectors to bytes by multiplication by sector size. This multiplication 
is accomplished by shifting the register pair AX:BX and the register CX 
left the number of bits in the sector size (sector size is constrained to be 
a power of 2). The physical address of the RAM buffer is added to the offset 
in AX:BX to give the starting address of the transfer. 

The RAM buffer is mapped to ES:DI, and the address of the IOCtl Data 
Buffer is placed in DS:SI. The contents of the data buffer are copied into 
the RAM buffer. The mapping is terminated, and the routine terminates. 

6.7.1.10 Read Strategy Routine The Read routine maps the applica¬ 
tion buffer whose address is contained in the READ strategy packet. This 
address will be used as a target of the copy operation. 

The address of the RAM buffer from which data is to be copied into the 
application buffer is then computed. The starting sector number from the 
READ packet is multiplied by sector size, and placed in AX:BX. The 
number of sectors to be transferred is multiplied by sector size, and is 
placed in CX. The base address of physical memory is then added to 
AX:BX. The physical address of the transfer being in AX:BX and its length 
in CX, the mapping operation is performed to DS:SI. 
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Flowchart 6.7.1.9 
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Flowchart 6.7.1.10 
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The mapped address of the application buffer is placed in ES:DI. The 
data from the RAM buffer is copied into the application buffer, and both 
maps are terminated. Completion status is set in the strategy packet, and 
the routine returns. 

6.7.1.11 Write Strategy Routine The Write routine maps the applica¬ 
tion buffer whose address is contained in the READ strategy packet. This 
address will be used as a source of the copy operation. 

The address of the RAM buffer to which data is to be copied into the 
application buffer is then computed. The starting sector number from the 
WRITE packet is multiplied by sector size, and placed in AX:BX. The 
number of sectors to be transferred is multiplied by sector size, and is 
placed in CX. The base address of physical memory is then added to 
AX:BX. The physical address of the transfer being in AX:BX and its length 
in CX, the mapping operation is performed to ES:DI. 

The mapped address of the application buffer is placed in DS:DI. The 
data from the application buffer is copied into the RAM buffer, and both 
maps are terminated. Completion Status is set in the strategy packet, and 
the routine returns. 

6.7.2 STRAT 

Device driver STRAT$ must be loaded before RAMDRV. STRAT$ cont ains 
an extra segment which is used to store the contents of strategy packets 
sent by RAMDRV. The interface to RAMDRV is at the IDC entry point. 
The contents of the extra segment are dumped to an application in 
response to a DosRead API call. 

6.7.2.1 Initialization At initialization, STRAT$ saves the device hel¬ 
per entry point. It then locks the extra data segment stratdata. The 
address stratdata is converted to a physical address, and stored for later 
use. The length of the code and data segments are stored into the INIT 
packet, and the routine returns to the kernel. 
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Flowchart 6.7.1.11 
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Flowchart 6.7.2.1 
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6 . 7 . 2.2 Read The STRAT$ read routine returns the entire contents of 
the extra data segment stratdata to the application. The length of the 
data contained in stratdata is in stratcount, stratcount is set to 0, clearing 
the stratdata buffer for the next IDC entry. 

The address of stratdata is mapped to DS:SI, and the application buffer 
is mapped to ES:DI. The contents of stratdata (all strategy packets 
written by the IDC routine) are written to the application buffer. The map 
is then terminated, and the routine returns. 

6.7.2.3 IDC Entry At entry to the IDC routine, STRAT$ assumes 
ES:BX points to the strategy packet whose contents are to be copied to 
the extra se gm ent, stratdata. The address of the next available byte in 
stratdata is computed as the physical address of stratdata added to 
stratcount. This address is mapped to ES:DI with a length equal to the 
strategy packet length. The address of the strategy packet is placed in 
DS:SI, and the contents of the packet are copied into stratdata. The 
ma pping is terminated and the IDC routine returns to the caller. 

6.7.3 Compile and Run 

Driver STRAT$ must be loaded before RAMDRV in file CONFIG.SYS. 
STRAT$ is loaded with command DEVICE=STRAT.SYS, and RAMDRV 
with DEVICE=RAMDRV.SYS. 

File DMPSTRAT.C dumps the contents of the strategy buffer main¬ 
tained by STRAT$. The contents of strategy packets received by RAMDRV 
(except the INIT packet) are recorded by STRAT$ at entry to and entry 
from RAMDRV. The buffer is cleared after dumping. 

File FORMAT.C must be used to format the logical unit before data 
may be written to the RAM device driver. Program FORMAT.C prepares 
the media by writing the boot sector, the FAT, and the root directory. A 
volume label is written to the root directory. FORMAT may be used to 
format any OS/2 logical unit. 

File RAMDRV.CMD contains the CL and LINK commands to compile 
and link programs FORMAT.C and DMPSTRAT.C, and the MASM and 
LINK co mma nds to create the device driver load modules STRAT and 
RAMDRV. 
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Flowchart 6.7.2.3 
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Files FORMAT.DEF and DMPSTRAT.DEF contain the NAME com¬ 
mand, specifying that the FORMAT and RAMDRV programs may run 
under the Presentation Manager. File RAMDRV.DEF contains the 
LIBRARY directive, required by all device drivers. File STRAT.DEF 
contains the LIBRARY directive, and the SEGMENTS directive. The 
SEGMENTS directive is used to specify the extra data segment as IOPL. 
The segments maindata and maincode must be specified in the SEG¬ 
MENTS directive to preserve their order in the load module. Lis tin gs of 
these files are contained in Appendix H. 

6.8 Programming Tools 

The sample programs in Appendices F, G, and H were written in Microsoft 
MASM 5.1 and Microsoft C 5.1 under Microsoft OS/2 1.05 Software 
Developers’ Kit (SDK). 

Supplemental documentation is provided in the Microsoft Driver 
Development Kit (DDK) and by IBM in their Operating System/2 Tech¬ 
nical Reference vl.l. Microsoft University provides a course in device 
driver development, available at their site in Redmond, Washington, or 
on-site through the author. 

Drivers can be written in C. C language support routines developed by 
the author are available separately. For ordering information please refer 
to the last page of this book. 

The debugging environment used for the sample programs is provided 
as part of the DDK. Additional hardware and software environments are 
becoming available. The reader is encouraged to contact the author for 
current information on these and other issues. 
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DRIVER STRUCTURES 


The device driver must have a driver header located at offset 0 of the main 
data segment. The format of this structure is shown in Table A-l. 


Table A-l: Driver Header Format 


NAME 

NEXTHEADER 


DAW 


STRATEGY 


FORMAT DESCRIPTION 

FAR POINTER Pointer to next header within driver 
file, allowing definition of multiple 
device drivers sharing the same data 
segment. Value -1 means no headers 
follow this header. Multiple headers 
are supported only for character 
drivers. 

WORD The device attribute word. The con¬ 

figuration of the driver is specified to 
the file manager with the bit fields 
contained in the DAW. The DAW is 
described below. 

WORD Offset within main code segment of 

the strategy routine entry point. 
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Table A-l; Driver Header Format _ 

NAME FORMAT DESCRIPTION 

IDC WORD Offset within main code segment of 

the Inter-Device Driver Communica¬ 
tion entry point (character device 
drivers only). 

NAME 8 BYTES For character devices, the blank-filled 

name of the device. For block drivers, 
byte 0 of this field is set by OS/2 to 
the number of logical units this driver 
supports. 

RESERVED 8 BYTES 


Table A-2 shows the format of the Device Attribute Word (DAW). 


Table A-2: DAW Format _ 

BIT NUMBER DESCRIPTION 

Bit 15 CHR, 1 for character device drivers, 0 for block device 

drivers. 

Bit 14 IDC, 1 if inter-device driver communication is supported 

by this device driver. 

Bit 13 IBM. For block drivers, 1 for DOS 2.0 file format, 0 for 

DOS 1.0 file format. For character device drivers, 1 for 
output-until-busy write support, 0 for all writes will com¬ 
plete with full character counts. 

Bit 12 SHR, For character devices, 1 = file manager should pro¬ 

vide shared file access protection, 0 = driver will arbitrate. 

Bit 11 OPN, For block drivers, 1 for removable media support, 0 

for fixed media. For character drivers, 1 for device 
OPEN/CLOSE if supported by driver, 0 if not. 

Bits 9-7 LEVEL, Set this field to 001 for OS/2 drivers, 000 for com¬ 

patibility box drivers. 

CLK, Set if this is driver replaces the system clock driver. 
NUL, Set if this driver replaces the system NULL device. 


Bit 3 
Bit 2 
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Table A-2: DAW Format _ 

BIT NUMBER DESCRIPTION 

Bit 1 SCR, Set if this driver replaces the system standard out¬ 

put device. 

Bit 0 KBD, Set if this driver replaces the system input device 

(keyboard). 


RAM semaphores may be allocated by the device driver. RAM 
semaphores are represented with a single DWORD area initialized to 0. 
The virtual address of this DWORD is passed to semaphore management 
DevHlp routines. Strategy queues are represented by a single DWORD 
area initialized to 0. The virtual address of this area is passed to the 
strategy queueing routines. The driver can tell if the strategy queue is 
empty by determining if the contents of this DWORD are 0. 

Character queues are represented by a six-byte queue header and a 
circular buffer. The length of the buffer must be specified before initializ¬ 
ing the queue. The driver may determine if the character queue is empty 
by checking the word at offset 4 of the queue header, for value 0. The 
format of character queues is shown in Table A-3. 


Table A-3: Character Queue Format 

CODE 

DESCRIPTION 

QSIZE DW size 

The word at offset 0 of the queue header must 
be initialized to the size of the queue. 

OUTINDEX DW ? 

The word at offset 2 of the queue header con¬ 
tains the index of the next character waiting to 
be read from the queue. 

QCOUNT DW ? 

The word at offset 4 of the queue header con¬ 
tains the number of characters held in the 
queue. If 0, the queue is empty. 

BUFFER DB size DUP (?) 

The driver must allocate space for the circular 
buffer at offset 6 of the queue structure. 
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Monitor packets are composed of a monitor word followed by the 
driver-defined packet. The monitor word’s format is shown in Table A-4. 


Table A-4: Monitor Word Format 


POSITION 

NAME 

DESCRIPTION 

Bit 0 

OPEN 

This packet is written to the monitor chain by the 
device driver in response to a monitor OPEN com¬ 
mand. Its meaning is defined by the driver. 

Bit 1 

CLOSE 

This packet is written to the monitor chain by the 
device driver in response to a monitor CLOSE com¬ 
mand. Its meaning is defined by the driver. 

Bit 2 

FLUSH 

This packet is written to the monitor chain by the 
monitor dispatcher in response to the driver Mon- 
Flush DevHlp request. Monitor threads are expected 
to flush their buffers and write this packet back to 
the monitor chain. 

Bits 8-OFh 

DRIVER- 

DEFINED 

This byte is reserved for definition and use by the 
device driver. 


The global INFO segment is used to determine date, time, and other 
process-independent information. The address of this segment is 
returned from DevHlp service, GetDOSVar. The format of the global 
INFO segment is shown in Table A-5. 


Table A-5: Global INFO Segment Format 


NAME 

UNIT 

DESCRIPTION 

TIMESECONDS 

DWORD 

Time in seconds since January 1, 1970. 

BOOTMS 

DWORD 

Time in milliseconds since booting. 

HOUR 

BYTE 

Time of day in hours (0-23). 

MINUTE 

BYTE 

Time of day in minutes. 

SECONDS 

BYTE 

Time of day in seconds. 

HUNDREDTHS 

BYTE 

Time of day in .01 seconds. 

TIMEZONE 

WORD 

Time zone in minutes. 
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Table A-5: Global INFO Segment Format 


NAME 

UNIT 

DESCRIPTION 

CLOCKTICK 

WORD 

Clock tick interval in .1 milliseconds. 

DAY 

BYTE 

Day of month. 

MONTH 

BYTE 

Month of year. 

YEAR 

WORD 

Current year (1980-2079). 

WEEKDAY 

BYTE 

Day of week (0=Sunday). 

MAJOR 

BYTE 

Major OS/2 version number. 

MINOR 

BYTE 

Minor OS/2 version number. 

LETTER 

BYTE 

OS/2 version letter. 

FGSCREEN 

BYTE 

Screen group currently in the foreground. 

SCREENMAX 

BYTE 

Maximum number of screen groups. 

SHIFT 

BYTE 

Huge segments shift count. (4) 

PROTONLY 

BYTE 

1 = Protect Mode-Only configuration (no 
compatibility box). 

FGPROCID 

WORD 

Process ID of process that holds keyboard 
focus. 

DYNAMIC 

BYTE 

1 = Dynamic priority scheduling is 
enabled. 

MAXWAIT 

BYTE 

Maximum waiting time in seconds (used 
for scheduling purposes). 

MINSLICE 

WORD 

Minimum time-slice in milliseconds a 
thread will be given when scheduled. 

MAXSLICE 

WORD 

Maximum time-slice in milliseconds a 
thread will be given when scheduled. 

BOOTDRIVE 

WORD 

Boot device, 1=A, 2=B. 

TRACE 

32 BYTE 

Enables tracing of major OS/2 events. 

MAXVIO 

BYTE 

Maximum number of VIO windowable ap¬ 
plications in the PM screen group. 

MAXPM 

BYTE 

Maximum number of PM applications. 
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The local INFO segment is used to obtain process and thread ID, and 
other process-dependent information. The address of this segment is 
returned from DevHlp service, GetDOSVar. The format of the local INFO 
segment is shown in Table A-6. 


Table A-6: Local INFO Segment Format 


NAME 

UNIT 

DESCRIPTION 

PROCID 

WORD 

Process ID. 

PARENTID 

WORD 

Parent’s process ID. 

PRIORITY 

WORD 

Thread scheduling priority. 

THREADID 

WORD 

thread ID 

SCREENGROUP 

WORD 

Screen group. 

SUBSCREEN 

WORD 

Subscreen group. 

FOCUS 

WORD 

-1 if process owns keyboard focus. 

TYPE 

BYTE 

Process type: 

0 = Full screen application 

1 = Real-mode process 

2 = VIO windowable process 

3 = PM application 

4 = Detached application. 

RESERVED 

BYTE 


ENVIRONMENT 

WORD 

Selector that points to environment 
segment. 

COMMAND 

WORD 

Offset of command line within en¬ 
vironment segment. 

DATASIZE 

WORD 

Initial size of DGROUP data seg¬ 
ment. 

STACKSIZE 

WORD 

Initial size of stack segment. 

HEAPSIZE 

WORD 

Initial size of heap segment. 

MODULE 

WORD 

Module handle. 

DGROUP 

WORD 

Selector that points to the DGROUP 
segment. 
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STRATEGY ROUTINES 


When the strategy routine is called by the kernel, the tiled address of a 
strategy packet is placed in ES:BX. A 13-byte header is common to all 
packets. The header contains information that is to be used by the driver, 
and it returns completion status to the kernel. The general strategy 
packet header format is shown below in Table B-l. 


Table B-l: Strategy Packet Header Format 


CODE 

UNIT 

DESCRIPTION 

LENGTH 

BYTE 

Set by the kernel to length of the strategy 
packet including this header. 

UNIT 

BYTE 

For block devices only, set by the kernel to 
the number of the logical unit to which this 
packet is directed. 

COMMAND 

BYTE 

Set by the kernel to the command code repre¬ 
senting the action the driver is expected to 
take in response to this packet. 
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Table B-l: Strategy Packet Header Format 

CODE 

UNIT 

DESCRIPTION 

STATUS 

WORD 

On input to character device drivers in the 
OPEN and CLOSE strategy packets, this 
field contains a single bit set by the kernel to 
distinguish between the monitor 

OPEN/CLOSE function and a device 
OPEN/CLOSE function. On output, the 
driver sets completion and error status to 
this field. 

RESERVED 

DWORD 

This field is reserved for future use by OS/2, 
and should not be used by the driver. 

LINKAGE 

DWORD 

This field may be used by the driver for its 
own purposes. 


The format of the STATUS word of the strategy header at input to the 
strategy routine is shown in Table B-2. 


Table B-2: STATUS Word Format 

FIELD 

MASK 

DESCRIPTION 

MON (bit 3) 

8 

At entry to the strategy routine, a character 
device driver should check the MON bit of the 
OPEN or CLOSE packet. 

MON 

=0 

Means this is a device OPEN or CLOSE com¬ 
mand. 

MON 

=1 

Means this is a monitor OPEN or CLOSE re¬ 
quest. 


Before exit from the strategy routine, the STATUS word is set as shown 
in Table B-3. 
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Table B-3: STATUS Word 

FIELD 

MASK 

DESCRIPTION 

ERROR (bit 15) 

8000h 

If set, this flag indicates to the kernel that an 
error has taken place, and the error code has 
been placed in the ERROR CODE field of the 
STATUS word. Device Driver Standard Error 
Codes 0-13h are translated by the kernel into 
OS/2 standard errors. User-Defined Error 

Codes placed in user-defined IOCtl packets 
(category codes 80h-0FFh) are returned un¬ 
translated, but QRed with value OFFOOh. 

DEVERROR 
(bit 14) 

4000h 

If set in conjunction with the ERROR flag of 
the STATUS word, the error code placed in 
the ERROR code field is interpreted by the 
driver as a Driver-Defined Error Code, not an 
OS/2 Device Driver Standard Error Code. 
Driver-Defined error codes are not translated 
by the kernel to OS/2 standard errors, but are 
ORed with value OFEOOh. 

BUSY (bit 9) 

200h 

The BUSY flag is set in response to status re¬ 
quests INPUT STATUS, OUTPUT STATUS, 
NONDESTRUCTIVE READ NO WAIT, and 
REMOVABLE MEDIA. 

DONE (bit 8) 

lOOh 

The DONE bit is set by the driver to indicate 
completion of I/O service. If the strategy 
routine returns with the DONE bit set, the 
kernel returns error status and unblocks the 
waiting thread. If the driver returns with 
DONE=0, the kernel blocks the thread until 
the device driver issues the device helper 
routine DevDone from interrupt or other con¬ 
text. 

ERROR CODE 
(bits 0-7) 

OFFh, byte 
0 

In case of error, the device driver places the 
error code in this field. Three classes of error 
are defined. 


In response to the INPUT STATUS and NONDESTRUCTIVE READ 
NO WAIT packets, the driver sets the BUSY bit to 1 if characters are not 
waiting for immediate read. In response to the OUTPUT STATUS packet, 
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the driver sets the BUSY bit to 1 to indicate the driver is in the process 
of writing characters to the device, and that any WRITE request issued 
the driver will have to wait for service. In response to the REMOVABLE 
MEDIA packet, the driver sets the BUSY bit to 1 if the media is fixed, and 
to 0 if the media is removable. 

The Device Driver Standard Error Codes are listed in Table B-4. 


Table B-4: Device Driver Standard Error Codes 

ERROR CODE 

DESCRIPTION 

0 

Write Protection Violation 

1 

Unknown Unit 

2 

Device Not Ready 

3 

Unknown Command 

4 

CRC Error 

5 

Bad Drive Request Structure Length 

6 

Seek Error 

7 

Unknown Media 

8 

Sector Not Found 

9 

Printer Out of Paper 

OAh 

Write Fault 

OBh 

Read Fault 

OCh 

General Failure 

lOh 

Uncertain Media 

llh 

Character I/O Call Interrupted 

12h 

Monitors Not Supported 

13h 

Invalid Parameter 


Table B-5 is a listing of all the strategy packets. It is followed by tables 
for each individual packet’s format. 
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Table B-5: Strategy Packets 


PACKET 

COMMAND CODE # 

DESCRIPTION 

INIT 

Command Code 0 

Initialize Device Driver 

MEDIA CHECK 

Command Code 1 

Check Removable Media (Block 
Drivers Only). 

BUILD BPB 

Command Code 2 

Build BIOS Parameter Block 
(Block Drivers Only). 

READ 

Command Code 4 

Read Data from Device. 

WRITE 

Command Code 8 

Write Data to Device. 

WRITE VERIFY 

Command Code 9 

Write Data to Device, then Verify 
Data Integrity (Block Drivers 
Only). 

NONDESTRUC¬ 
TIVE READ NO 
WAIT 

Command Code 5 

Peek at first waiting character, 
but do not remove it from queue 
(Character Devices Only). 

INPUT STATUS 

Command Code 6 

Determine if any characters are 
waiting in the input queue (Char¬ 
acter Devices Only). 

OUTPUT STATUS 

Command Code OAh 

Determine if the output device is 
busy (Character Devices Only). 

INPUT FLUSH 

Command Code 7 

Flush the input queue (Character 
Devices Only). 

OUTPUT FLUSH 

Command Code OBh 

Flush the output queue (Charac¬ 
ter Devices Only). 

OPEN 

Command Code ODh 

Open a channel between file 
manager and device. 

CLOSE 

Command Code OEh 

Close previously opened channel 
between file manager and device. 

REMOVABLE 

MEDIA 

Command Code OFh 

Determine if media is removable 
(Block Devices Only). 

GENERIC IOCtl 

Command Code lOh 

Send special I/O commands to 
device. 

RESET MEDIA 

Command Code llh 

Reset "Uncertain Media" error 
(Block drivers only). 

DEINSTALL 

Command Code 14h 

Terminate the device driver 
(Character Drivers Only). 
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Table B-5: Strategy Packets 


PACKET COMMAND CODE # 

PAR- Command Code 16h 

TITIONABLE 

FIXED DISKS 

GET FIXED Command Code 17h 

DISK/LOGICAL 

UNIT MAP 


DESCRIPTION 

Return number of physical drives 
supported by this device driver 
(Block Drivers Only). 

Return the list of logical units 
supported on a physical drive 
(Block Drivers Only). 


Table B-6; INIT Packet Format on Entry to Strategy Routine 


NAME 

FORMAT 

DESCRIPTION 

Request Header 

13 BYTES 

Standard strategy request packet 
described above. 

Unused 

BYTE 


DevHlpAddress 

FAR POINTER 

A tiled pointer to the entry point of 
the Device Helper Routines provided 
by OS/2 for use by the device driver. 

Init Ad dress 

FAR POINTER 

Pointer to the NULL-terminated ar¬ 
gument string contained in the 
DEVICE= line of CONFIG.SYS. 

StartUnit 

BYTE 

For block devices only, the logical 
unit number of the first unit of this 
driver. 


Table B-7: INIT Packet Format on Return from Strategy Routine 

NAME FORMAT DESCRIPTION 

Request Header 13 BYTES Standard strategy request packet 

described above. 

NumUnits BYTE For block drivers only, number of 

logical units this driver manages. 
Character devices set this field to 0. 
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Table B-7: INIT Packet Format on Return from Strategy Routine 


NAME 

FORMAT 

DESCRIPTION 

EndOfCode 

WORD 

Set by driver to the length of the 
main code segment after initializa¬ 
tion. If initialization fails, set this 
field to 0. 

EndOfData 

WORD 

Set by driver to the length of the 
main data segment after initializa¬ 
tion. If initialization fails, set this 
field to 0. 

BPBAddress 

FAR POINTER 

For block drivers only, pointer to an 
array of near pointers to BIOS 
Parameter Blocks, one per logical 
unit. Character device should set 
this field to 0. 


Successful initialization is indicated by setting the STATUS word of 
the request header to lOOh, DONE with no error. Initialization failure 
should be indicated by setting the STATUS word of the request header to 
810Ch, General Failure. 


Table B-8: MEDIA CHECK Packet (Command Code 1) Format 


name format 

Request Header 13 BYTES 

Media Descriptor BYTE 
ChangeCode BYTE 


DESCRIPTION 

Standard strategy request packet 
described above. 

The media descriptor byte for the cur¬ 
rent media is determined and 
returned to the file manager. 

Set by driver to indicate to the file 
manager whether the media has 
changed: 

-1 = Media has been changed 
0 = Unsure if media has been 
changed 

1 = Media has not been changed. 
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Table B-8: MEDIA CHECK Packet (Command Code 1) Format 


NAME 

LabelAddress 


FORMAT 
AR POINTER 


DESCRIPTION 

Pointer to volume label of previous 
media. If the driver does not keep 
the volume label, a pointer to the 11- 
byte blank-filled, NULL-terminated 
string "NO NAME" should be 
returned. 


Table B-9: BUILD BPB Strategy Packet (Command Code 2) Format 


NAME FORMAT 

Request Header 13 BYTES 

Media Descriptor BYTE 

BootSector FAR POINTER 


BPBptr FAR POINTER 


DESCRIPTION 

Standard strategy request packet 
described above. 

The media descriptor byte for the cur¬ 
rent media is determined by the 
driver, and returned to the file 
manager. 

On entry to the strategy routine; a vir¬ 
tual pointer to the boot sector, read by 
the file manager. This address is valid 
only in strategy context. For drivers 
that support DOS 1.0 and 1.1 file sys¬ 
tems (as indicated by 0 in the IBM bit 
of the driver attribute word), this sec¬ 
tor will contain the first sector of the 
File Allocation Table. 

The device driver determines the 
media descriptor byte, the volume 
label, and the BIOS parameter block 
for the current media. The virtual ad¬ 
dress of the BPB is returned by the 
driver in this field. 



APPENDIX B 377 


Table B-10: READ (4), WRITE (8), and WRITE VERIFY (9) Formats 


NAME 

FORMAT 

DESCRIPTION 

Request Header 

13 BYTES 

Standard strategy request packet 
described above. 

Media Descriptor 

BYTE 

The media descriptor byte for the cur¬ 
rent media is set into the strategy packet 
by the file manager, and is available to 
the driver. This byte is provided primari¬ 
ly for compatibility with earlier systems. 

BufferAddress 

DWORD 

The 24-bit physical buffer address is 
provided by the file manager. This buffer 
has been locked, but must be mapped by 
the driver to a virtual address before use. 

TransferCount 

WORD 

For character devices, the number of 
characters to be transferred. For block 
devices, the number of sectors to be 
transferred. 

StartSector 

DWORD 

For block devices only, the address of the 
first sector of the transfer. Sectors are 
numbered from 0. 

FileNumber 

WORD 

A unique number assigned by the file 
manager which represents the file to 
which I/O is being performed. This num¬ 
ber may be used to implement caching 
schemes. 


Table B-ll: NONDESTRUCTIVE READ NO WAIT (5) Format 


NAME 

FORMAT 

DESCRIPTION 

Request Header 

13 BYTES 

Standard strategy request packet 
described above. 

ReturnedChar 

BYTE 

The driver places the first character in 
the input queue into this field. The char¬ 
acter remains in the queue. If no charac¬ 
ter is waiting, the driver returns value 
300h in the STATUS word of the request 
header (setting BUSY and DONE flags). 
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Table B-12: INPUT (6) and OUTPUT (OAh) STATUS Packet Formal 

NAME FORMAT DESCRIPTION 

Request Header 13 BYTES Standard strategy request packet 

described above.1 


For INPUT STATUS, place value 300h in the STATUS word of the 
request header (setting BUSY and DONE flags) if a READ request cannot 
be immediately serviced because no characters are available in the input 
queue. For OUTPUT STATUS, place value 300h in the STATUS word if 
a WRITE request cannot be immediately serviced because another 
WRITE request is pending, or the device is busy. 


Table B-13: INPUT (7) and OUTPUT (OBh) FLUSH Packet Formats 

NAME FORMAT DESCRIPTION 

Request Header 13 BYTES Standard strategy request packet 

described above. 


For INPUT FLUSH, flush the input queue and terminate all pending 
READ requests. For OUTPUT flush, flush the output queue and ter¬ 
minate all pending WRITE requests. 


Table B-14: OPEN (ODh) and CLOSE (OEh) Strategy Packet Formats 

NAME 

FORMAT 

DESCRIPTION 

Request Header 

13 BYTES 

Standard strategy request packet 
described above.l 

FileNumber 

WORD 

A unique number, assigned by the file 
manager, that represents the file to 
which I/O is being performed. This num¬ 
ber may be used to implement caching 
schemes. 



APPENDIX B 379 


The OPEN/CLOSE request issued to character drivers is often used by 
the driver to arbitrate device ownership. Test the MON bit (bit 3) to 
determine if this is a device or monitor OPEN request. For block drivers, 
the OPEN/CLOSE request may be used to implement file-sensitive cach¬ 
ing schemes. 

Table B-15: REMOVABLE MEDIA (OFh) Strategy Packet Format 

name format description 

Request Header 13 BYTES Standard strategy request packet 

described above. 


Set the STATUS word to lOOh if the media for this logical unit is 
removable, and to 300h if the media is fixed. 


Table B-16: GENERIC IOCtl (lOh) Strategy Packet Format 


NAME 

Request Header 

FORMAT 

13 BYTES 

CATEGORY 

BYTE 

FUNCTION 

BYTE 

PARAMETERBUF- 

FER 

FAR POINTER 

DATABUFFER 

FAR POINTER 

FILENUMBER 

WORD 


DESCRIPTION 

Standard strategy request packet 
described above. 

Category code for the generic I/O 
command. 

Function code (within category code) 
for the generic I/O command. 

The parameter buffer is a virtual ad¬ 
dress whose format and interpreta¬ 
tion are not defined by OS/2. 

The data buffer is a virtual address 
whose format and interpretation are 
not defined by OS/2. 

A unique number associated with the 
file channel opened to the device. 
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Table B-17: RESET MEDIA (llh) Strategy Packet Format _ 

name format description 

Request Header 13 BYTES Standard strategy request packet 

described above. The file manager is¬ 
sues this request to inform the 
driver it need no longer post the "Un¬ 
certain Media" error. 


Table B-18; DEINSTALL (14h) Strategy Packet Format __ 

name format description 

Request Header 13 BYTES Standard strategy request packet 

described above. 


If an attempt is made to load a character driver whose name is already 
in use by a loaded device driver, the earlier driver will be posted this 
request. The driver receiving this request can accept deinstallation by 
releasing all resources and returning value lOOh in the STATUS word, or 
refuse the request by posting 8103h to the STATUS word (Unknown 
Command). 

Table B-19: PARTITIONABLE FIXED DISKS (16h) Packet Format 

name format description 

Request Header 13 BYTES Standard strategy request packet 

described above. 

NumberDrives BYTE Place the number of physical drives 

the driver supports in this field. 
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Table B-20: GET FIXED DISK/LOGICAL UNIT MAP (17h) Formats 

CODE 

FORMAT 

DESCRIPTION 

Request Header 

13 BYTES 

Standard strategy request packet 
described above. The UNIT field con¬ 
tains the physical drive number to 
which this request is directed. 

BitMask 

4 BYTES 

Set each bit whose number is equal to 
a logical unit number supported on 
this physical drive. Bits are num¬ 
bered right to left within a byte, and 
bytes are numbered sequentially. 
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SYSTEM-DEFINED IOCtl PACKETS 


The system defines IOCtl packets for certain devices or classes of func¬ 
tions. These packets have a category code from 0-127, and error codes 
returned from the driver are translated to appropriate OS/2 error codes. 
Users may define additional packets that their drivers will service in the 
category code range 128-255. Error codes returned from these packets are 
returned to the application without translation—other than ORing in the 
value OFFOOh (to indicate user-defined error). 

Drivers that wish to provide full support of all OS/2 system software 
should be able to handle the IOCtls the system has defined. This appendix 
will document the system IOCtls defined for logical unit support, physical 
drive support, character device support, and monitor support. Table C-l 
shows the IOCtl strategy packet’s format. 


Table C-l: IOCtl Strategy Packet Format (Command Code lOh) 


NAME 

TYPE 

DESCRIPTION 

Request Header 

13 Bytes 

Standard strategy request packet 
described above (Appendix A). 

CATEGORY 

BYTE 

Category code for the generic I/O 
command. Category commands 
which will be described in this ap¬ 
pendix are: 
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Table C-l: IOCtl Strategy Packet Format (Command Code lOh) 


NAME TYPE 

FUNCTION BYTE 

PARAMETERBUF- FAR POINTER 
FER 

DATABUFFER FAR POINTER 

FILENUMBER WORD 


DESCRIPTION 

8 = Logical Unit Support 

9 = Physical Drive Support 
OAh = Monitor Support 

OBh = Character Device Support. 

Function code (within category 
code) for the generic I/O command. 

PARAMETERBUFFER is the vir¬ 
tual address of a buffer whose for¬ 
mat and interpretation are not 
defined by OS/2. 

DATABUFFER is the virtual ad¬ 
dress of a buffer whose format and 
interpretation are not defined by 
OS/2. 

A unique number associated with 
the file channel opened to the 
device. 


The following is a list of the Category 8 IOCtls (Logical Unit Support). 


Lock Drive 

Category 8, Function 0 


Lock logical unit (serviced by file manager). 


Parameter Buffer Format: 

COMMAND BYTE Should be set to 0 by application 

before making this call. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by application 

__before making this call. 
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Unlock Drive 
Category 8, Function 1 


Unlock logical unit (serviced by file manager). 


Parameter Buffer Format: 

COMMAND BYTE Should be set to 0 by application 

before making this call. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by application 

before making this call. 


Redetermine Media 
Category 8, Function 2 _ 

Read BPB and volume label information. 


Parameter Buffer Format: 

COMMAND BYTE Should be set to 0 by application 

before making this call. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by application 

before making this call. 


Block Removable 
Category 8, Function 20h 


Determine if media is removable. 


Parameter Buffer Format: 
COMMAND BYTE 


Should be set to 0 by application 
before making this call. 
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Block Removable 
Category 8, Function 20h 


Data Buffer Format: 

REMOVABLEFLAG BYTE Set by the driver to the state of the 

media: 

0 = removable media 
1 = fixed media. 


Get Device Parameters 
Category 8, Function 63h 


Get the BIOS parameter block for the logical unit. 


Parameter Buffer Format: 

COMMAND BYTE 

0 = Return the recommended BPB 
for the device. 

1 = Return the BPB for the current 
media. 

Data Buffer Format: 


BPB 

31 BYTES 

Extended BPB. 

CYLINDERS 

WORD 

Number of cylinders. 

DEVTYPE 

BYTE 

Device Type: 

0 = 48 tpi low density diskette 

1 = 96 tpi high density diskette 

2 = 720K 3-1/2 inch diskette 

3 = 8 inch single density diskette 

4 = 8 inch double density diskette 

5 = Fixed diskette 

6 = Tape drive 

7 = Other. 

DEVATTR 

WORD 

Device attributes: 

Bit 0 = Removable media flag (1 = 
removable) 

Bit 1 = Fixed media flag (1 = fixed). 
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Set Device Parameters 

Category 8, Function 43h _ 

Set the BIOS parameter block for the logical unit. 


Parameter Buffer Format: 

COMMAND BYTE 0 = Reset device parameters to their 

original state. 

1 = Change the default BPB. 

2 = Change the'BPB for the current 
media. 

Data Buffer Format: 

BPB 31 BYTES 

CYLINDERS WORD 

DEVTYPE BYTE 


Extended BPB. 
Number of cylinders. 
Device Type: 


DEVATTR WORD 


Device attributes: 

Bit 0 = Removable media flag (1 = 
removable) 

Bit 1 = Fixed media flag (1 = fixed). 


Write Track 

Category 8, Function 44h 

Write sector(s) on a track. 


Parameter Buffer Format: 

LAYOUT BYTE Track layout format: 

0 = Use track layout table to trans¬ 
late from logical sector number to 
physical sector number. 

1 = Sectors are numbered sequential¬ 
ly (track layout table must still be 
specified). 
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Write Track 



Category 8, Function 44h 


HEAD 

WORD 

Head number of track to be writ¬ 
ten/read/verified. 

CYLINDER 

WORD 

Cylinder number of track to be writ¬ 
ten/read/verified. 

STARTSECTOR 

WORD 

Logical sector number of first sector 
transferred/verified (starting at 0). 

SECTORCOUNT 

WORD 

Number of sectors to be trans¬ 
ferred/verified. All sectors must lie 
within a single track. 

LAYOUTTABLE 

2 words per sec¬ 
tor on track 

The track layout table specifies the 
logical sector number associated 
with each physical sector. The logical 
sector number is used as an index 
into the track layout table. The two 
words in the layout table are physi¬ 
cal sector number and sector size in 
bytes. 

Data Buffer Format: 


DATA 

BYTE 

Should be set to 0 by application 
before making this call. 

Read Track 



Category 8, Function 64h 


Read sector(s) from a track. 


Parameter Buffer Format: 

Same as for Write Track. 


Data Buffer Format: 

Same as for Write track. 
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Verify Track 
Category 8, Function 65h 


Verify sector(s) on a track. 


Parameter Buffer Format: 

Same as for Write Track. 

Data Buffer Format: 

Same as for Write Track. 


Format Track 
Category 8, Function 45h 


Format and Verify Track. 


Parameter Buffer Format: 


LAYOUT 

BYTE 

Format layout format: 

- 


0 = Use format layout table to trans¬ 
late from logical sector number to 
physical sector number. 

1 = Sectors are physically numbered 
sequentially (track layout table must 
still be specified). 

HEAD 

WORD 

Head number of track to be formatted. 

CYLINDER 

WORD 

Cylinder number of track to be for¬ 
matted. 

RESERVED 

WORD 


SECTORCOUNT 

WORD 

Number of sectors on this track. 
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Format Track 
Category 8, Function 45h 


FORMATTABLE 4 bytes per sec- The format layout table specifies the 
tor on track interleave sequence of sectors on the 
track. The four bytes are cylinder 
number, head number, sector number, 
and sector size code. The sector size 
code is 0 for 128 bytes, 1 for 256 
bytes, 2 for 512 bytes, and 3 for 1,024 
bytes. Cylinder number is coded into a 
10 bit field, and head number is repre¬ 
sented in 6 bits. 


The following is a list of Category 9 IOCtls (Physical Drive Support). 


Lock Physical Drive 
Category 9, Function 0 


Lock physical drive (serviced by file manager and not passed to driver). 


Parameter Buffer Format: 

COMMAND BYTE Should be set to 0 by applica¬ 

tion before making this call. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by applica¬ 

tion before making this call. 


Unlock Physical Drive 
Category 9, Function 1 


Unlock physical drive (serviced by file manager and not passed to driver). 
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Unlock Physical Drive 
Category 9, Function 1 


Parameter Buffer Format: 

COMMAND BYTE Should be set to 0 by applica¬ 

tion before making this call. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by applica¬ 

tion before making this call. 


Physical Write Track 
Category 9, Function 44h 


Write sector(s) on a track. 


Parameter Buffer Format: 

LAYOUT BYTE Track layout format: 

0 = Use track layout table to 
translate from logical sector 
number to physical sector num¬ 
ber. 

1 = Sectors are physically num¬ 
bered sequentially (but track 
layout table must still be 
specified). 


HEAD 

WORD 

Head number of track to be writ¬ 
ten/read/verified. 

CYLINDER 

WORD 

Cylinder number of track to be 
written/read/verified. 

STARTSECTOR 

WORD 

Logical sector number of first 
sector to be transferred/verified 
(starting at 0). 

SECTORCOUNT 

WORD 

Number of sectors to be trans¬ 
ferred/verified. All sectors must 


lie within a single track. 
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Physical Write Track 
Category 9, Function 44h 


LAYOUTTABLE 2 words per sector on The track layout table specifies 
track the logical sector number as¬ 

sociated with each physical sec¬ 
tor. The logical sector number is 
used as an index into the track 
layout table. The two words in 
the layout table are physical sec¬ 
tor number, and sector size in 
bytes. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by application 

before making this call. 


Physical Read Track 
Category 9, Function 64h 


Physical Read sector(s) from a track. 


Parameter Buffer Format: 

Same as that of Physical Write Track. 

Data Buffer Format: 

Same as that of Physical Write Track. 


Verify Track 
Category 9, Function 65h 


Physical Verify sector(s) on a track. 


Parameter Buffer Format: 
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Verify Track 
Category 9, Function 65h 


Same as that of Physical Write Track. 

Data Buffer Format: 

Same as that of Physical Write Track. 


Get Physical Device Parameters 
Category 9, Function 63h_ 


Get device characteristics. 


Parameter Buffer Format: 


COMMAND 

BYTE 

Should be set to 0 by application 
before making this call. 

Data Buffer Format: 

RESERVED 

WORD 


CYLINDERCOUNT 

WORD 

Number of cylinders on device. 

HEADCOUNT 

WORD 

Number of heads for device. 

SECTORCOUNT 

WORD 


RESERVED 

8 BYTES 

Number of sectors on a track. 


The following is a Category OAh IOCtl (Monitor Support). 


Register a Monitor 
Category OAh, Function 40h 


Register a monitor. 


Parameter Buffer Format: 


r 
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Register a Monitor 
Category OAh, Function 40h 


COMMAND BYTE 

Data Buffer Format: 
PLACEMENT WORD 

INDEX WORD 

INPUTOFFSET WORD 

BUFFERSELECTOR WORD 

OUTPUTOFFSET WORD 


Should be set to 0 by application 
before making this call. 


Placement flag, as formatted by 
DosMonReg API call, and as 
passed to Register DevHlp service. 

Driver-defined word, formatted by 
DosMonReg API call, and inter¬ 
preted by driver. 

Offset of monitor input buffer, as 
formatted by DosMonReg API call, 
and as passed to Register DevHlp 
service. 

Selector of monitor buffers, as for¬ 
matted by DosMonReg API call, 
and as passed to Register DevHlp 
service. 

Offset of monitor output buffer, as 
formatted by DosMonReg API call, 
and as passed to Register DevHlp 
service. 


Table C-5 shows the Category OBh IOCtls (Character Device Control). 


Flush Input Buffer 
Category OBh, Function 1 


Flush input buffer. 


Parameter Buffer Format: 
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Flush Input Buffer 

Category OBh, Function 1 _ 

COMMAND BYTE Should be set to 0 by application 

before making this call. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by application 

before making this call. 


Flush Output Buffer 
Category OBh, Function 2 


Flush output buffer. 


Parameter Buffer Format: 

COMMAND BYTE Should be set to 0 by application 

before making this call. 

Data Buffer Format: 

DATA BYTE Should be set to 0 by application 

before making this call. 


Query Monitor Support 

Category OBh, Function 60h _ 

Return error code 8112h if monitors are not supported. 


Parameter Buffer Format: 

COMMAND BYTE Should be set to 0 by application 

before making this call. 


Data Buffer Format: 
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Query Monitor Support 
Category OBh, Function 60h 


Should be set to 0 by application 
before making this call._ 


DATA 


BYTE 
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DEVICE HELPER ROUTINES 


The device driver helper routines (DevHlp) share a common entry ad¬ 
dress. The DevHlp function code is placed in register DL. The DevHlp 
address is tiled and may be called from any context. Most DevHlp routines 
are constrained to operate in certain contexts. All arguments to DevHlp 
routines are placed in registers. The state of the interrupt flag is not 
preserved when a DevHlp routine returns from a block. In case of error, 
an error code is often returned in AL. These error returns are not 
standardized, but generally correspond to application error codes as found 
in BSEERR.INC. The following tables summarize the DevHlp services 
available to the device driver. 

AllocGDTSelector 
2Dh, Initialize Mode 

Allocate global selectors for later use by driver. 

Registers before call: 

ES:DI 


Address of array into which al¬ 
located selectors are to be 
placed. 
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AllocGDTSelector 
2Dh, Initialize Mode 


CX Number of selectors to be allo¬ 

cated. 

DL 2Dh, command code for 

AllocGDTSelector. 

Return Values: 

C bit of PSW clear No error. 

C bit of PSW set Error code in AX. 


AllocPhys 

18h, Initialize Mode, Strategy Mode 


Allocate physical memory. 


Registers before call: 

AX:BX Size of memory to be allo¬ 

cated. 

DH 0 to allocate high memory, 1 

for low memory. 

DL 18h, command code for Alloc¬ 

Phys. 

Return Values: 

C bit of PSW clear No error, starting physical ad¬ 
dress is in AX:BX. 

C bit of PSW set Error code in AX. 
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AllocReqPacket 

ODh, Strategy Mode 

Allocate a request packet 

Registers before call: 


DH 

0 for block until packet is 
available, 1 for return imme¬ 
diately with error if no pack¬ 
ets are available. 

DL 

ODh, command code for 
AllocReqPacket. 

Return Values: 


C bit ofPSW clear 

ES:BX contains the virtual 
address of the allocated 
packet. 

C bit of PSW set 

Packet was not available 


AttachDD 

2Ah, Initialize Mode, Strategy Mode 


Attach to a device driver. 


Registers before call: 

BX Offset of 8-character 

name of target device 
driver within main data 
segment. 

DI Offset of 12-byte area 

within main data seg¬ 
ment to contain attach 
\ data. The format of this 

area is: 
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AttachDD 


2Ah, Initialize Mode, Strategy Mode 


- Real-mode FAR pointer 
to IDC entry point of tar¬ 
get driver. 

- Real-mode DS value of 


target driver 
- Protect-mode FAR 


pointer to IDC entry 
point of target driver 
- Protect-mode DS value 
of target driver 

DL 

2Ah, command code for 
AttachDD. 

DS 

Must contain the selector 
for the main data seg¬ 
ment. 

Return Values: 


C bit of PSW clear 

12-byte area pointed at 
by DS:DI is filled in. 

C bit of PSW set 

Driver was not installed, 
or does not support IDC. 

Block 

4, Strategy Mode 

Block thread to be awakened later. 

Registers before call: 


AX:BX 

32 bit wake-up code. 

DI:CX 

Time-out interval in mil¬ 
liseconds. 

DH 

0 if block is interruptible 
when underlying process ter¬ 
minates, 1 if uninterruptable. 
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Block 

4, Strategy Mode 


DL 

4, command code for Block. 

Return Values: 

C bit of PSW clear 

Thread was awakened by Run 
DevHlp service. 


C bit of PSW set 

Unusual wakeup, wakeup code 
in AL. Z bit of PSW contains 
additional information. 


Z bit set 

Unusual wakeup was due to 
time-out. 


Z bit clear 

Unusual wakeup was due to 
underlying process termination 


DeRegister 

21h, Strategy Mode (protect only) 


Deregister all monitor threads on 

a specified chain with specified process ID. 

Registers before call: 

AX 

Handle returned from 
MonitorCreate service, repre¬ 
senting monitor chain. 

BX 

Process ID of threads which 
are to be removed from 
monitor chain. 

DL 

21h, command code for De- 
Register. 


Return Values: 

C bit of PSW clear AX contains number of 

monitors remaining on chain. 


AX contains error code. 


C bit of PSW set 
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DevDone 

1, Strategy Mode, Interrupt Mode 


Mark strategy packet as done, and unblocks thread waiting in the kernel on 
this packet. 


Registers before call: 

ES:BX Tiled address of strategy packet. 

DL 1, command code for DevDone. 


EOI 

31h, Interrupt Mode, Initialize Mode 


Dismiss interrupt request at PIC. 


Registers before call: 

AL IRQ number (O-OFh on AT and 

PS/2). 

DL 31h, command code for EOI. 


FreePhys 

19h, Initialize Mode, Strategy Mode 


Free physical memory allocated by AllocPhys. 


Registers before call: 

AX:BX Physical address of memory to be 

( deallocated. 

DL 19h, command code for FreePhys. 


Return Values: 
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FreePhys 

19h, Initialize Mode, Strategy Mode _ 

C bit of PSW Memory was deallocated 

clear 

C bit of PSW 
* set 


FreeReqPacket 

OEh, Strategy Mode _ 

Return request packet allocated with AllocReqPacket. 


Registers before call: 

ES:BX 

Tiled address of request packet. 

DL 

OEh, command code for FreeReq¬ 
Packet. 

GetDOSVar 

24h, Initialize Mode, Strategy Mode 

Get system variable. 

Registers before call: 

AL 

Index of system variable: 
l=global INFO selector 

2=local INFO selector 

5=reboot vector FAR pointer 

7=Yield byte 

8=TCYield byte. 

DL 

24h, command code for 

GetDOSVar. 


Memory was not allocated with 
AllocPhys. 


Return Values: 
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GetDOSVar 

24h, Initialize Mode, Strategy Mode _ 

C bit of PSW AX:BX contains the address of the 
clear variable. 

* C bit of PSW The variable was not returned, 

set 


Lock 

13h, Initialize Mode, Strategy Mode 

Lock virtual memory against relocation or swap. 


Registers before call: 

AX Selector value for segment to be 

locked. 

BH Lock type. 0 for short-term lock 

(segment will not be moved), 1 
for long-term lock, and 3 for ini- 
tialize-time permanent lock of 
device driver segment. The 
main data and code segments of 
the driver are in low memory, 
and therefore are already locked. 

BL For short term locks only, 0 for 

block until lock is complete, 1 
for do not block even if segment 
is not present in memory. For 
long term locks, 1 should be 
specified. 

DL 13h, command code for Lock 

Return Values: 

C bit of PSW clear Segment was locked. AX:BX con¬ 
tains a lock handle to be used 
with the Unlock service. 
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Lock 

13h, Initialize Mode, Strategy Mode __ 

C bit of PSW set Segment was not available, or 
invalid selector. AX and BX are 
corrupt. 


MonFlush 

23h, Strategy Mode (protect only) 


Flush data in specified monitor chain (block until done). 


Registers before call: 

AX 

Handle representing monitor 
chain, returned from DevHlp 
service MonitorCreate. 

DL 

23h, command code for Mon- 
Flush 

Return Values: 

C bit of PSW clear 

Monitor chain has been 
flushed. AX is not preserved. 

C bit of PSW set 

Error code is in AX. 

MonitorCreate 

lFh, Initialize Mode, Strategy Mode (protect only) 

Create monitor chain, destroy targeted chain. 

Registers before call: 

AX 

0 for create new handle. Non¬ 
zero to release existing chain. 
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MonitorCreate 

lFh, Initialize Mode, Strategy Mode (protect only) 


ES:SI 

If AX=0, address of final buffer 
into which character data pack¬ 
et will be written. 


DI 

If AX=0, offset of notification 
routine within main code seg¬ 
ment. 


DS 

DS must contain selector value 
for main data segment. 


DL 

lFh, command code for Monitor¬ 
Create. 

Return Values: 


C bit of PSW 

AX contains monitor chain hand- 


clear 

le for create 


C bit of PSW 
set 

AX contains error code. 


MonWrite 

22h, Interrupt Mode, Strategy Mode 

Write character packet to monitor. 


Registers before call: 

AX 

Monitor chain handle 
returned from MonitorCreate 

SI 

Offset of character packet in 
main data segment. 

CX 

Number of bytes in data pack- 


et. 
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MonWrite 

22h, Interrupt Mode, Strategy Mode 

DH 

0 to block if monitor chain is 
full, 1 for return with error. 1 
must be specified in interrupt 
mode. 

DS 

DS must contain selector 
value for main data segment. 

DL 

22h, command code for Mon- 
Write. 

Return Values: 

C bit of PSW 

Packet has been written to 

clear. 

monitor chain. AX is not 
preserved. 

C bit of PSW set 

AX contains error code. 


PhysToGDTSelector 

2Eh, Initialize Mode, Strategy Mode, Interrupt Mode 

Map physical memory segment to 

a global selector. 

Registers before call: 

AX:BX 

Physical address of memory 
segment to be mapped. 

CX 

Length of segment to be 
mapped. 

SI 

Global selector to be mapped. 

DL 

2Eh, command code for 
PhysToGDTSelector. 


Return Values: 

C bit of PSW clear Memory segment was 
mapped. 
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PhysToGDTSelector 

2Eh, Initialize Mode, Strategy Mode, Interrupt Mode 

C bit of PSW set Error code is in AX. 


PhysToUVirt 

17h, Initialize Mode, Strategy Mode 


Allocate a local selector and map physical memory segment, or deallocate 
local selector. 


Registers before call: 

DH 0 for map to read-only selec¬ 

tor, 1 for map to read/write 
selector, 2 for free selector. 

AX:BX Physical address of memory 

segment to be mapped if DH=0 
or 1. Selector to be released is 
in AX if DH=2. 

CX Length of segment to be 

mapped if DH=0 or 1. 

DL 17h, command code for 

PhysToUVirt. 


Return Values: 

C bit of PSW clear Selector was allocated and 

placed in ES:BX, and memory 
segment was mapped for 
DH=0 or 1; or selector was 
deallocated for DH=2. 

C bit of PSW set Invalid selector or address. 
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PhysToVirt 

15 h, Initialize Mode, Strategy Mode, Interrupt Mode 

Mode-Independent conversion of physical address to virtual address. 
Registers before call: 


AX.BX 

Physical address of memory seg¬ 
ment to be mapped. 

CX 

Length of segment to be 
mapped. 

DH 

0 for place result in DS:SI, 1 
for place result in ES:DI. 

DL 

15h, command code for PhysTo¬ 
Virt. 

DS 

Must point to main data seg¬ 
ment at first call to PhysToVirt. 


Return Values: 

C bit of PSW clear Segment was mapped, and 
result placed in selected 
register pair. Result must not 
be stored, no DevHlp routines 
may be called, and strategy 
routine must not block before 
the mapping is terminated with 
UnPhysToVirt. Z bit of PSW 
may be examined for further in¬ 
formation. 

C bit of PSW set AX contains error code. 

Z bit of PSW clear No change in addressing mode 
took place (previous transla¬ 
tion is still valid). 

Z bit of PSW set Addressing mode changed. If a 
previous mapping was made to 
the other register pair, that 
mapping is no longer valid and 
must be remapped. 
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ProtToReal 

30b, Strategy Mode, Interrupt Mode 


Return to real mode from protect mode (must follow RealToProt). 


Registers before call: 

DS 

DS must point to main 
data segment. 


DL 

30h, command code for 
ProtToReal. 

Return Values: 

C bit ofPSW clear 

Context has been 
returned to real mode. 


C bit ofPSW ofPSW set AX contains error code. 

PullParticuIar 



OBh, Strategy Mode, Interrupt Mode 


Remove specified request packet from request queue. 

Registers before call: 

SI 

Offset of queue head 
within main data segment. 


ES:BX 

Address of request packet 
to be removed from queue. 


DS 

DS must point to main 
data segment. 


DL 

OBh, command code for 
PullParticuIar. 

Return Values: 

C bit ofPSW clear 

Packet was removed from 
strategy queue. 
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PullParticular 

QBh, Strategy Mode, Interrupt Mode _ 

C bit of PSW set Request packet was not 
found 


PullReqPacket 

QAh, Strategy Mode, Interrupt Mode 


Remove first waiting request packet from request queue. 


Registers before call: 

SI 

Offset of queue head within 
main data segment. 


DS 

DS must point to main data 
segment. 


DL 

OAh, command code for Pull¬ 
ReqPacket. 

Return Values: 

C bit of PSW clear 

Packet was removed from 
strategy queue, and its ad¬ 
dress placed in ES:BX. 


C bit of PSW set 

Request queue was empty. 

PushReqPacket 

9h, Strategy Mode 


Place request packet on request queue. 


Registers before call: 
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PushReqPacket 
9h, Strategy Mode 


SI 

Offset of queue head within 
main data segment. 

ES:BX 

Address of request packet to 
be placed on queue. 

DS 

DS must point to main data 
segment. 

DL 

9, command code for Push¬ 
ReqPacket. 


QueueFlush 

10h, Strategy Mode, Interrupt Mode 


Flush character queue. 


Registers before call: 


BX 

Offset of character queue 
within main data segment. 

DS 

DS must point to main 
data segment. 

DL 

lOh, command code for 
QueueFlush. 


Queuelnit 

OFh, Initialize Mode, Strategy Mode, Interrupt Mode 


Initialize character queue. 
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Registers before call: 

BX 

Offset of character queue 
within main data segment. 

DS 

DS must point to main data 
segment. 

DL 

OFh, command code for 
Queuelnit. 

QueueRead 

12h, Strategy Mode, Interrupt Mode 

Remove character from character queue. 

Registers before call: 

BX 

Offset of character queue 
within main data segment. 

DS 

DS must point to main data seg¬ 
ment. 

DL 

12h, command code for Queue- 
Read. 

Return Values: 

C bit of PSW 
clear 

AL contains the character read 
from the queue. 

C bit of PSW set 

Character queue was empty. 

QueueWrite 

llh. Strategy Mode, Interrupt Mode 

Place character in character queue. 


Registers before call: 
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f 


QueueWrite 


llh, Strategy Mode, Interrupt Mode 

BX 

Offset of character queue 
within main data segment. 

AL 

Character to be placed in char¬ 
acter queue. 

DS 

DS must point to main data 
segment. 

DL 

llh, command code for Queue- 
Write. 

Return Values: 


C bit of PSW clear 

Character has been written to 
queue. 

C bit of PSW set 

Character queue was full. 

RealToProt 


2Fh, Strategy Mode, Interrupt Mode 

Change context from real to protect. 

Registers before call: 


DS 

DS must point to main data 
segment. 

DL 

2Fh, command code for Real¬ 
ToProt. 


Return Values: 
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RealToProt 

2Fh, Strategy Mode, Interrupt Mode 


C bit of PSW clear 

Context has been changed 
to protect mode. Strategy 
routine must not return or 
block until context has been 
restored to real mode with 
ProtToReal. Interrupt 
routine must resume real 
mode before returning. 


C bit of PSW set 

Context has not been 
changed. 


Register 

2Oh, Strategy Mode (protect only) 


Register a monitor thread to a monitor chain. 


Registers before call: 

AX 

Handle of monitor chain 
returned from MonitorCreate. 

ES 

Selector pointing to segment 
containing input and output 
buffers. 

SI 

Offset of input buffer. 

DI 

Offset of output buffer. 

DH 

Placement flag (supplied by 
DosMonReg). 

DL 

20h, command code for 
Register. 


Return Values: 

C bit of PSW clear Monitor has been placed on 

monitor chain. 
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Register 

20h, Strategy Mode (protect only) _ 

C bit of PSW set AX contains error code. 


RegisterStackUsage 
38h, Initialize Mode 


Register interrupt stack size requirements. 


Registers before call: 



DS 

DS must point to main data seg¬ 
ment. 


BX 

Offset of registration parameter 
block within main data segment. 


DL 

38h, command code for Register¬ 
StackUsage 

Registration Parameter Block: 


BLOCKSIZE 

DW 14 

Size of parameter block. 

ENABLEFLAG 

WORD 

0 if interrupt routine runs dis¬ 
abled, 1 if interrupt routine 
enables interrupts. 

IRQNUMBER 

WORD 

IRQ number of interrupt hand¬ 
ler. 

CLISTACK 

WORD 

Stack requirements while inter¬ 
rupts are disabled. 

STISTACK 

WORD 

Stack requirements after inter¬ 
rupts are enabled, while IRQ 
level is disabled at the PIC. 

EOISTACK 

WORD 

Stack requirements after IRQ 
level is enabled at the PIC, 
during which period nested in¬ 
terrupts may occur. 

NESTLEVEL 

WORD 

Maximum nesting level 
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RegisterStackUsage 
38h, Initialize Mode 


Return Values: 

C bit of PSW 
clear 

Stack requirements are avail¬ 
able. 


C bit of PSW set 

Insufficient stack space exists 
to satisfy driver requirements. 

ResetTimer 

IF.Vi, Initialize Mode, Strategy Mode, Interrupt Mode 

Remove a timer handle for device driver. 

Registers before call: 

AX 

Offset within code segment 
of entry point of timer hand¬ 
ler to be removed. 


DS 

DS must point to main data 
segment. 


DL 

lEh, command code for 
ResetTimer. 


Return Values: 


C bit of PSW Timer handler has been 

clear removed. 

C bit of PSW set Handler was not available 
for removal. 
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Run 

5, Strategy Mode, Interrupt Mode 

Release thread(s) waiting on Block. 

Registers before call: 


AX:BX 

32-bit wakeup code 
specified in Block. 

DL 

5, command code for Run. 

Return Values: 


Z bit of PSW clear 

AX contains number of 
threads which were 
awakened (waiting on 
same wakeup code). 

Z bit of PSW set 

No threads were waiting 
on wakeup code. AX con¬ 
tains 0. 


SemClear 

7, Strategy Mode, Interrupt Mode 


Release a semaphore. 


Registers before call: 

AX:BX 

DL 

Semaphore handle. 

7, command code for Sem¬ 
Clear. 

Return Values: 

C bit of PSW clear 

Semaphore was released. 


C bit of PSW set 

AX contains error code. 
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/ 


SemHandle 

8, Strategy Mode, Interrupt Mode 


Convert system semaphore handle to driver handle, or release driver handle. 


Registers before call: 


AX:BX 

System semaphore handle 
provided to underlying 
process by DosCreateSem 
to be converted, or handle 


to be released. 

DH 

1 to create a driver hand¬ 
le, 0 to release a driver 
handle. 

DL 

8, command code for Sem¬ 
Handle. 


Return Values: 

C bit of PSW clear AX:BX contains driver 
handle by which driver 
may refer to semaphore (if 
DH was 1). 

C bit of PSW set AX contains error code. 


SemRequest 

6, Strategy Mode _ 

Claim a semaphore, and block until available. 


Registers before call: 


AX:BX 

Semaphore handle. 

DI:CX 

Timeout interval in mil¬ 
liseconds (-l=forever) 

DL 

6, command code for Sem¬ 
Request. 
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SemRequest 
6, Strategy Mode 


Return Values: ~~ 

C bit of PSW clear Semaphore was claimed. 
C bit of PSW set AX contains error code. 


SetIRQ 

lBh, Initialize Mode, Strategy Mode 


Attach an interrupt service routine to an IRQ level. 


Registers before call: 


AX 

Offset of interrupt service 
entry point in main code seg¬ 
ment. 

BX 

IRQ number (O-OFh on AT or 
PS/2). 

DH 

0 for exclusive ownership of 

IRQ level, 1 for allocate shared 
IRQ level. 

DS 

DS must point to the main 
data segment. 

DL 

lBh, command code for SetIRQ. 


Return Values: 


C bit of PSW clear Interrupt service routine has 
been attached to IRQ level. 

IRQ level was not available. 


C bit of PSW set 
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SetTimer 

lDh, Initialize Mode, Strategy Mode 

Attach a timer routine to driver. 


Registers before call: 

AX 

Offset of timer routine entry 
point in main code segment. 

DS 

Must be set to selector value 
for main data segment. 

DL 

lDh, command code for Set- 
Timer. 

Return Values: 

C bit of PSW clear 

Timer routine has been at¬ 
tached to driver. 

C bit of PSW set 

Timer routine was already set, 
or too many timer routines 
(system maximum of 32). 


SortReqPacket 
OCh, Strategy Mode 


Place request packet on request queue 
number. 

in ascending order of starting sector 

Registers before call: 

SI 

Offset of queue head within 
main data segment. 


ES:BX 

Address of request packet to be 
placed on queue. 


DS 

DS must point to main data seg¬ 
ment. 
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SortReqPacket 
OCh, Strategy Mode 


DL OCh, command code for SortReq¬ 

Packet. 


TCYield 

3, Strategy Mode 


Block strategy routine if a time-critical thread of higher priority is waiting. 


Registers before call: 

DL 


3, command code for TCYield. 


TickCount 

33h, Initialize Mode, Strategy Mode, Interrupt Mode 


Attach a timer routine to driver to be called every N ticks. 


Registers before call: 

AX 


BX 

DS 

DL 


Offset of timer routine entry 
point in main code segment. 
The timer routine must al¬ 
ready have been registered in 
interrupt mode. 

N, the number of ticks be¬ 
tween calls to the timer 
routine. 

Must be set to selector value 
for main data segment. 

33h, command code for Tick- 
Count. 
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TickCount 

33h, Initialize Mode, Strategy Mode, Interrupt Mode 


Return Values: 

C bit of PSW clear Timer routine has been at¬ 
tached to driver, and tick 
count was set to N. 

C bit of PSW set Timer routine cannot be set, 

or too many timer routines 
(system maximum of 32). 


Unlock 

14h, Initialize Mode, Strategy Mode 


Unlock virtual memory earlier locked with DevHlp service Lock. 


Registers before call: 

AX:BX Lock handle returned from 

DevHlp service Lock. 

DL 14h, command code for Un¬ 

lock. 

Return Values: 

C bit of PSW clear Segment was unlocked. 

C bit of PSW set Invalid handle, or memory 

cannot be unlocked. 


UnPhysToVirt 

32h, Initialize Mode, Strategy Mode, Interrupt Mode 


Terminate PhysToVirt mapping. 
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UnPhysToVirt 

32h, Initialize Mode, Strategy Mode, Interrupt Mode 


Registers before call: 

DL 

32h, command code for Un¬ 
PhysToVirt. 

Return Values: 


DS 

DS restored to point to main 
data segment. 

ES 

ES is not preserved. 

Z bit of PSW clear 

Mapping terminated without 
mode change. 

Z bit of PSW set 

Mapping terminated with 
mode change from protect to 
real. 


UnSetIRQ 

ICh, Initialize Mode, Strategy Mode, Interrupt Mode 


Disconnect interrupt service routine from IRQ. 


Registers before call: 


BX 

IRQ level to be released (0- 
OFh on AT or PS/2). 

DS 

Selector value for main data 
segment. 

DL 

ICh, command code for 
UnSetIRQ. 


Return Values: 

C bit of PSW clear Interrupt service routine is 
disabled, and IRQ level avail¬ 
able to be attached to other 
interrupt service routine. 
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UnSetIRQ 

ICh, Initialize Mode, Strategy Mode, Interrupt Mode 

C bit of PSW set 

IRQ level was not owned (or 
shared) by device driver. 

VerifyAccess 

27h, Strategy Mode 

Verify access rights of underlying process to memory region. 

Registers before call: 

AX:DI 

Virtual address of region 
whose accessibility to under¬ 
lying thread is to be verified. 

CX 

Length of region in bytes (0 
means 64K bytes). 

DH 

0 if read-only access is 
desired, 1 if read/write 
privilege is required. 

DL 

27h, command code for 
VerifyAccess. 

Return Values: 


C bit of PSW clear 

Memory region was acces¬ 
sible. The driver should lock 
this memory before block¬ 
ing, as the effects of a block 
on memory access rights is 
unpredictable. 

C bit of PSW set 

Memory region was not ac¬ 
cessible by underlying 
thread. Underlying process 
is terminated. 
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VirtToPhys 

16h, Initialize Mode, Strategy Mode 


Convert virtual locked address to physical address. 


Registers before call: v 


DS:SI 

Virtual address to be trans¬ 
lated to physical address. 

DL 

16h, command code for Virt¬ 
ToPhys. 

Return Values: 


C bit of PSW clear 

AX:BX contains physical ad¬ 
dress. 

C bit of PSW set 

Virtual address could not be 
translated. 

Yield 

2, Strategy Mode 


Block strategy routine if any thread of higher priority is waiting. 


Registers before call: 


DL 


2, command code for 
Yield. 
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PHYSICAL FILE FORMAT 


The file structure impressed upon a physical drive, and upon a logical 
unit with a physical drive, is dictated by file manager conventions, 
physical drive partitioning conventions, and conventions established by 
the ROM BIOS. Physical drive partitioning constraints are followed only 
for devices that will support FDISK, and ROM BIOS conventions need be 
followed only for devices that are to boot from the BIOS. 

The ROM BIOS requires logical sector 0 (track 0, head 0, physical sector 
1) of the physical drive to contain a boot sector. The boot sector format is 
described in Table E-l. 


Table E-l: Boot Sector Format 

NAME 

LENGTH 

DESCRIPTION 

JMPCode 

3 BYTES 

3-byte JMP instruction, causing execution 
to flow to the BootCode area. 

VendorlD 

8 BYTES 

8-byte, vendor-defined identification. 

BPB 

19 BYTES 

BPB (in short format). The short BPB can 
only support devices with 64K sectors,^ or 
32M with the default 512 byte sector size. 

BootCode 

482 BYTES 

Code to allow continuation of boot process. 


427 
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If it is desirable to use OS/2 logical unit partitioning software (FDISK), 
the boot sector contains a partition table at offset IBEh. This partition 
table contains partition information for four partitions and a signature 
word. Only two partitions are used by OS/2, a partition description for 
the current partition, and a pointer to the boot sector of the next partition. 
The boot sector of the next partition contains a partition table for its 
partition, and points in turn to the following partition. Format of the 
partition table is shown in Table E-2. 


Table E-2: Partition Table Format 


TABLE ENTRY LENGTH 

PARTITION1 16 BYTES 

PARTITION2 16 BYTES 

PARTITION3 16 BYTES 

PARTITION4 16 BYTES 

SIGNATURE WORD 


DESCRIPTION 
Description of partition #1. 
Description of partition #2. 
Description of partition #3. 
Description of partition #4. 
Contains 55AAh. 


The format of each partition description entry is shown in Table E-3. 


Table E-3: Partition Description Entry Formats 


NAME 

LENGTH 

DESCRIPTION 

BOOT 

BYTE 

Bootstrap indicator. 

HEADSTART 

BYTE 

Head number of start of partition. 

SECTORSTART 

BYTE 

Sector number of start of partition. 

CYLSTART 

BYTE 

Cylinder number of start of partition. 
Cylinder number is a 10 bit field. 

PartID 

BYTE 

Partition Identifier. Valid partition codes 
are: 

0 = No space allocated in this partition. 
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Table E-3: Partition Description Entry Formats _ 

NAME LENGTH DESCRIPTION 

1 = DOS partition under 20,740 sectors 
(12-bit FAT entries for devices up to 
10M, see below). 

4 = DOS partition over 10M (20,740 sec¬ 
tors) and under 32M (16-bit FAT entries, 
short BPB format). 


5 = Pointer to next extended volume. 

6 = DOS partition over 32M (16-bit FAT, 
extended BPB format). 


HEADEND 

BYTE 

Head number of end of partition. 

SECTOREND 

BYTE 

Sector number of end of partition. 

CYLEND 

BYTE 

Cylinder number of end partition. 

Cylinder number is a 10-bit field. 

PARTSTART 

DWORD 

Sector number of start of partition. Sec¬ 
tor number is counted from boot sector. 

PARTLEN 

DWORD 

Length of partition in sectors. 


Table E-4 shows the Short (19 byte) BIOS Parameter Block Format. 


Table E-4: Short BIOS Parameter Block Format 

NAME LENGTH DESCRIPTION 

SECTORSIZE WORD Sector size in bytes, normally 512. 

CLUSTERSIZE BYTE Number of sectors in a single allocation. 

Each entry in the File Allocation Table 
will represent one cluster of sectors. The 
cluster size must be a power of 2. 

Number of sectors reserved in the logi¬ 
cal unit for the boot area. The File Al¬ 
location Table follows the boot area. 


BOOTSECTORS WORD 
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Table E-4: Short BIOS Parameter Block Format 


NAME 

LENGTH 

DESCRIPTION 

FATCOUNT 

BYTE 

Number of File Allocation Tables. Nor¬ 
mally 2 FATs are allocated, but only one 
is maintained by the file manager. 

ROOTENTRIES 

WORD 

Number of 32 byte entries provided in 
the root directory. 

UNITSIZE 

WORD 

Total number of sectors on the logical 
unit, including boot area, FATs, and root 
directory. 

DESCRIPTOR 

BYTE 

Media descriptor byte. 

FATSIZE 

WORD 

Size of FAT in sectors. 

TRACKSIZE 

WORD 

Size of track in sectors. 

HEADCOUNT 

WORD 

Number of heads. 

HIDDENSIZE 

WORD 

Number of sectors preceding this logical 
unit on the physical drive. 


Table E-5 shows the Extended (31 byte) BIOS Parameter Block Format. 


Table E-5: Extended BIOS Parameter Block Format 


NAME 

LENGTH 

DESCRIPTION 

SECTORSIZE 

WORD 

Sector size in bytes, normally 512. 

CLUSTERSIZE 

BYTE 

Number of sectors in a single alloca¬ 
tion. Each entry in the File Allocation 
Table will represent one cluster of sec¬ 
tors. The cluster size must be a power 
of 2. 

BOOTSECTORS 

WORD 

Number of sectors reserved in the logi¬ 
cal unit for the boot area. The File Al¬ 
location Table follows the boot area. 

FATCOUNT 

BYTE 

Number of File Allocation Tables. Nor¬ 
mally 2 FATs are allocated, but only 
one is maintained by the file manager. 
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Table E-5: Extended BIOS Parameter Block Format 


NAME 

LENGTH 

DESCRIPTION 

ROOTENTRIES 

WORD 

Number of 32 byte entries provided in 
the root directory. 

EBPBFLAG 

WORD 

This word is 0 for the Extended BPB. 

DESCRIPTOR 

BYTE 

Media descriptor byte. 

FATSIZE 

WORD 

Size of FAT in sectors. 

TRACKSIZE 

WORD 

Size of track in sectors. 

HEADCOUNT 

WORD 

Number of heads. 

HIDDENSIZE 

DWORD 

Number of sectors preceding this logi¬ 
cal unit on the physical drive. 

UNITSIZE 

DWORD 

Total number of sectors on the logical 
unit, including boot area, FATs, and 
root directory. 

RESERVED 

6 BYTES 

Reserved for future definition. 


The File Allocation Table (FAT) follows the boot area on the logical uni t. 
Each entry in the FAT represents one cluster on the logical unit. Entries 
in the FAT are 12 bits in length for devices of size 16M or less, and 16 bits 
for those larger than 16M. The maximum number of clusters is 64K. 

Each FAT entry represents a single cluster. FAT entry 0 represents 
cluster 0, FAT entry 1 represents cluster 1, etc. The value of the FAT entry 
marks the cluster as free for allocation, bad, or already allocated. Clusters 
are allocated in "chains," where each cluster points to the next allocated 
cluster in the file. The values -8 through -1 represent the last cluster in 
a chain. 

Cluster numbers 0 and 1 are always allocated for the boot area. The 
media descriptor byte is placed in FAT entry 0, and -1 is placed in FAT 
entry 1. The media descriptor byte may have values -8 through -1. Cluster 
2 corresponds to the first available cluster in the unallocated data area 
of the logical unit. Table E-6 lists the possible FAT values: 
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Table E-6: FAT Entries 


12 BIT ENTRY 

16 BIT ENTRY 

DESCRIPTION 

0 

0 

Free Cluster. 

1 

1 

Never used. 

2-OFEFh 

2-OFFEFh 

This cluster is in use, and the 
value of this FAT entry points to 
the next cluster in the chain. 

0FF0h-0FF6h ' 

0FFF0h-0FFF6h 

Reserved values. 

0FF7h 

0FFF7h 

Bad Cluster. 

0FF8h-0FFFh 

0FFF8h-0FFFFh 

This cluster is in use, and is the 
last cluster in the chain. 


The root directory follows the FATs on the logical unit. Each directory 
L entry is 32 bytes in length (so 16 entries are contained in a 512 byte 
sector). The format of each directory entry is depicted in Table E-7. 


Table E-7; Directory Entry Formats 


FILENAME 8 BYTES 

EXTENSION 3 BYTES 

ATTRIBUTE BYTE 


DESCRIPTION 

The filename, extended with blanks to 
make 8 bytes. If used for a volume label, 
FILENAME and EXTENSION are con¬ 
sidered together to make a blank-filled, 11- 
byte volume label. 

The file extension, extended with blanks 
to make 3 bytes. 

The file attributes are described in this 
byte. Value 0 represents a normal file. Pos¬ 
sible bit-valued attributes are: 

1 = Read-only file 

2 = Hidden file 
4 = System file 

8 = Volume label 
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Table E-7: Directory Entry Formats 


RESERVED 10 BYTES 
UPDATETIME WORD 


UPDATEDATE WORD 


FIRSTCLUSTER WORD 

DWORD 


DESCRIPTION 


The time of file creation or last update. 
The time is encoded into this word as fol¬ 
lows: 

Bits 11-15 = Hour 
Bits 5-10 = Minute 
Bits 0-4 = Second/2. 

The date of file creation or last update. 
The date is encoded into this word as fol¬ 
lows: 

Bits 9-15 = Year since 1980 

Bits'5-8 = Month 

Bits 0-4 = Day of month. 

Index of first cluster in file, and index to 
FAT entry which points in turn to next 
cluster of file. 

Size of file in bytes. 


FILESIZE 
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SAMPLE PROGRAMS/PIPER.ASM 


This appendix contains the programs described in Section 6.5. 


PIPER.ASM _ 

PAGE ,132 

TITLE Pipe Device Driver for OS/2 


.286 _ 

; FILE : PIPER.ASM 

r 

; Sample Device Driver for OS/2 

; Manages a pipe for inter process communication. 

/ 

; entry: ES:BX has pointer to packet 
; DS has main data segment of device driver 


; devices supported : PIPEIN$, PIPEOUT$ 

/ 

; open packets are queued until device available 

ram semaphore is used to coordinate read, write, and close 
; one common character queue is used 

; two queues are used for opens, one for in and one for out 
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st din 

stdout 

stderr 

cr 

If 


equ 0 
equ 1 
equ 2 

equ Odh 
equ Oah 


; DevHelp Function Codes 

/ 

PhysToUVirt 

Queuelnit 

QueueFlush 

QueueWrite 

QueueRead 

SemRequest 

SemClear 

ProcBlock 

ProcRun 

PushRequest 

PullRequest 

PullParticular 

GetDOSVar 

LocallnfoSeg 


; Character Queue 


equ 17h 
equ Ofh 
equ lOh 
equ llh 
equ 12h 
equ 06h 
equ 07h 
equ 04h 
equ 05h 
equ 09h 
equ Oah 
equ Obh 
equ 24h 

equ 02h 


Qsize 

dw 

o 

Qchrout 

dw 

? 

Qcount 

dw 

? 

Qbase 

db 

o 


size of Queue in bytes 
index of the next character out 
count of characters in Queue 
indicates start of Queue Buffer 


Queuelnit 

mov bx,offset ds:[queue] 

mov dl,Queuelnit 

call [DEVHELP] 


QueueWrite 

mov bx,offset ds:[queue] 

mov al,character 

mov dl,QueueWrite 


/points to Queue Structure 
/Qsize field must be already setup 

/points to Queue Structure 
/item to put on queue 
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call [DEVHELP] 


QueueRead 

mov bx,offset ds:[queue] 

mov dl,QueueRead 

call [DEVHELP] 


QueueFlush 

mov bx,offset ds:[queue] 

mov dl,QueueFlush 

call [DEVHELP] 


SemRequest 

mov bx,SemHandleLow 

mov ax,SemHandleHigh 

mov cx,TimeoutLow 

mov di,TimeoutHigh 

mov dl,SemRequest 

call [DEVHELP] 


SemClear 

mov bx,SemHandleLow 

mov ax,SemHandleHigh 

mov dl,SemClear 

call [DEVHELP] 


ProcBlock 

mov bx,EventIdLow 

mov ax,EventIdHigh 

mov cx,TimeoutLow 

mov di,TimeoutHigh 

mov dh,InterruptableFlag 

mov dl,ProcBlock 

call [DEVHELP] 


;c flag is set if queue is full 
;C cleared if write successful 


/points to Queue Structure 

;C flag is set if queue is empty 
;C cleared if read is successful 
;AL gets char 

/points to Queue Structure 
/clears queue structure 


/word ptr for RAM semaphore 
/in milliseconds (-l=forever) 
/C flag set if error 


/word ptr for RAM semaphore 
;C flag set if error 


/for this example use strategy 
/packet address es:bx 
/in milliseconds 
/-I waits forever 

;C flag set if unusual wakeup 
/Z flag set if timeout 
/AL awake code, non-zero for 
/ unusual wakeup 
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ProcRun 


mov 

bx, EventldLow 

/for this example use strategy 

mov 

ax, Event IdHigh 

/packet address es:bx 

mov 

dl,ProcRun 


call 

[DEVHELP] 



PhysToUVirt 


mov 

ax,AddressHigh 


mov 

bx,AddressLow 

/physical address 

mov 

cx,Length 


mov 

dh,RequestType 

/0-get virt addr read/executable 

mov 

dl,PhysToUVirt 

/1-get virt addr read/write 
/2-free virt addr 

call 

[DEVHELP] 


PushRequest 

mov 

si,offset queue 

/ds must point to main data segment 
/pointer to head of device list 

les 

bx,RequestPacket 

/pointer to device RequestPacket 

mov 

dl,PushRequest 


call 

[DEVHELP] 



PullRequest 

;ds must point to main data segment 
mov si,offset queue /pointer to head of device list 

mov dl, PullRequest 

call [DEVHELP] 

;C flag clear if no error 
/es:bx points to device packet 
;C flag set if no packet 

PullParticular 

;ds must point to main data segment 
mov si,offset queue /pointer to head of device list 




APPENDIX F 439 


les bx,RequestPacket /pointer to device RequestPacket 

mov dl,PullParticular 

call [DEVHELP] 

;C flag clear if no error 
;c flag set if no packet found 


GetDOSVar 

mov al, VarNumber 
mov dl,GetDOSVar 
call [DEVHELP] 


;2-LocalInfoSeg 

;C flag cleared if no error 
;ax:bx=bimodal pointer to variable 


LocallnfoSeg STRUCT 


CurProcId 

dw 

(?) 

/current process id 

ParProcId 

dw 

(?) 

/process id of parent 

CurThrdPri 

dw 

(?) 

/current thread priority 

CurThrdld 

dw 

(?) 

/current thread id 

CurScrnGrp 

dw 

(?) 

/screen group 

SubScrnGrp 

dw 

(?) 

/sub screen group 

Fgnd 

dw 

(?) 

/current process is in foreground 

RealMode 

db 

(?) 

/current process is in real mode 

fillerl 

db 

(?) 

/filler byte 


LocallnfoSeg ENDS 


extrn DosWrite: far 


DGROUP group __DATA 

__DATA segment word public 'DATA' 


/device header blocks 
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hdrin 


hdrout 


page 

INDISP 


dd 

r hdrout 

;start of second device header 

dw 

8880h 

;OS/2 character 

device, 



/accepts opens, 

level 1 

dw 

Stratln 

/beginning of strategy routine 

dw 

0 



db 

"PIPEIN$ " 

/name of device 

(must be 8 bytes) 

db 

8 dup (0) 



dd 

-1 

dw 

8880h 

dw 

StratOut 

dw 

0 

db 

,, PIPEOUT$" 

db 

8 dup (0) 


LABEL 

WORD 



dw 

Initln 

/ *0 - 

initialize device driver 

dw 

Error 

; l - 

media check 

dw 

Error 

; 2 - 

build BIOS parameter block 

dw 

Error 

/ 3 - 

not used 

dw 

Readln 

/ *4 - 

read from device 

dw 

Error 

; 5 - 

nondestructive read 

dw 

Error 

/ 6 - 

input status 

dw 

Error 

/ 7 - 

flush device input buffers 

dw 

Writeln 

; *8 - 

write to device 

dw 

Error 

/ 9 - 

write then verify 

dw 

Error 

; 10 

- output status 

dw 

Error 

/ 11 

- flush output buffers 

dw 

Error 

; 12 

- not used 

dw 

Openln 

/ *13 

- device open 

dw 

Closeln 

/ *14 

- device close 

dw 

Error 

; 15 

- removable media 

dw 

Ok 

/ 16 

- generic IOCTL 

dw 

Error 

; 17 

- reset media 

dw 

Error 

; 18 

- get logical drive 

dw 

Error 

/ 19 

- set logical drive 

dw 

Error 

/ 20 

- deinstall 

dw 

Error 

/ 21 

- not used 

dw 

Error 

; 22 

- partitionable fixed disks 

dw 

Error 

/ 23 

- get fixed disk unit map 

dw 

Error 

/ 24 

- not used 
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dw 

dw 

maxcmdin = 


(($ 


Error 

Error 


- INDISP)/2) 


; 25 - not used 
; 26 - not used 
- 1 
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OUTDISP LABEL WORD 


dw 

InitOut 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Readout 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

WriteOut 

dw 

/Error 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

OpenOut 

dw 

CloseOut 

dw 

Error 

dw 

Ok 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Error 

dw 

Error 


maxcmdout = (($ - OUTDISP)/2) 


;*0 - initialize device driver 

; 1 - media check 

; 2 - build BIOS parameter block 

; 3 - not used 

; *4 - read from device 

; 5 - nondestructive read 

; 6 - input status 

; 7 - flush device input buffers 

;*8 - write to device 

; 9 - write then verify 

; 10 - output status 

; 11 - flush output buffers 

; 12 - not used 

;*13 - device open 

;*14 - device close 

; 15 - removable media 

; 16 - generic IOCTL 

; 17 - reset media 

; 18 - get logical drive 

; 19 - set logical drive 

; 20 - deinstall 

; 21 - not used 

; 22 - partitionable fixed disks 
; 23 - get fixed disk unit map 

; 24 - not used 

; 25 - not used 

; 26 - not used 

1 


page 

DEVHELP DD ? 


CURPID 


DW ? 


; Pointer to device driver help routine 
; Current process ID from LocallnfoSeg 
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PINPID 

DW 

o 

• / 

PINOCT 

DW 

? / 

PINOPENQ 

DD 

? 

WRRAMSEM 

DD 

? 

WRCLOSE 

DW 

? 

WRCTR 

DW 

O ; 

WRBLCTR 

DW 

? / 

WRBUFSIZ 

DW 

? ; 

WRBUFPTR 

DD 

O ; 

WRPKTID 

DD 

? ; 


POUTPID 

DW 

? 

/ 

POUTOCT 

DW 

o 


POUTOPENQ 

DD 

o 

/ 

RDRAMSEM 

DD 

o 

; 

RDCTR 

DW 

o 

r 

RDBUFSIZ 

DW 

? 

; 

RDBUFPTR 

DD 

o 

/ 

RDPKTID 

DD 

o 

/ 


PIPEIN Owner Process ID 

PIPEIN open count 

Pointer to PIPEIN Request Queue 

Write RAM Semaphore 

Write Close Flag 

Write Counter 

Write after BLOCK Counter 

Write Packet Buffer Size 

Pointer to User Write Buffer 

Write Packet Id 


PIPEOUT Owner Process ID 

PIPEOUT open count 

Pointer to PIPEOUT Request Queue 

Read RAM Semaphore 

Read Counter 

Read Packet Buffer Size 

Pointer to User Read Buffer 

Read Packet Id 


CQSTRUCT 

STRUC 


Qsize 

Qchrout 

Qcount 

Qbase 

dw 8 
dw ? 
dw ? 

db 8 dup (?) 

;size of Queue in bytes 
;index of the next character out 
;count of characters in Queue 
/indicates start of Queue Buffer 

CQSTRUCT 

ENDS 


CHARQ 

CQSTRUCT <> 

/allocates storage for structure 

Idln 

db cr,If 
db "PIPEIN$ / 
db cr,If 

Write Only Sample OS/2 Device Driver 

Idln^len 

equ $-IdIn 


IdOut 

db cr,If, If 
db "PIPEOUT$ 

, Read Only Sample OS/2 Device Driver 
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db cr,lf 

IdOut_len equ $-IdOut 

/receives length returned from DosWrite at INIT time 
wlen *dw ? 

DgrpEnd label byte 

_DATA ends 

page 

TEXT segment word public 'CODE' 

assume cs:_JFEXT,ds:DGROUP,es:NOTHING 

Stratln: ;PIPEIN$ strategy entry point 

;ES:BX = request packet address 


mov 

di,es:[bx+2] 

/get command from packet 

and 

di,Offh 


cmp 

di, maxcmdin 


jg 

Error 

/bad command 

add 

di, di 


jmp 

word ptr [di+INDISP] 



StratOut: ;PIPEOUT$ strategy entry point 
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;ES:BX = request packet address 


mov 

and 

di,es:[bx+2] 
di,Offh 

/get 

command from packet 

cmp 

di,maxcmdout 



jg 

add 

Error 
di, di 

;bad 

command 

jmp 

word ptr [di+OUTDISP] 




Ok: 

mov word ptr es:[bx+3],OlOOh ;set status = OK 
retf 


Error: 

mov es:[bx+3], 810CH ;set status = general failure 

retf 


page 

/ 

; Initialize PIPEIN$ (section 6.5.1.1) 


Initln: 

mov ax,es:[bx+14] ;get DevHelp offset 

mov word ptr DEVHELP,ax 

mov ax,es:[bx+16] /get DevHelp segment 

mov word ptr DEVHELP+2,ax 


; put end of code and data segments back into request packet 


mov 

mov 


word ptr es:[bx+14],offset _TEXT:TextEnd 
word ptr es:[bx+16],offset DGROUP:DgrpEnd 
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initialize 

character queue 

push 

bx 

mov 

bx,offset ds:CHARQ 

mov 

dl,Queuelnit 

call 

[DEVHELP] 

pop 

bx 


initialize 

write variables (whether 

they need it or not) 

mov 

PINPID,-1 

;current write owner process id 

mov 

word ptr PINOPENQ,0 

/pointer to open request queue 

mov 

word ptr PINOPENQ+2,0 

/upper half 

mov 

PINOCT,0 

/write open counter (same owner) 

mov 

word ptr WRRAMSEM,0 

/write semaphore 

mov 

word ptr WRRAMSEM+2,0 

/upper half 

mov 

WRCLOSE,0 

/write close flag 

mov 

WRCTR, 0 

/write counter (bytes written) 

mov 

WRBLCTR,0 

/write counter after BLOCK 

mov 

MRBDFSXZ, 0 

/user write buffer size 

mov 

word ptr WRBDFPTR, 0 

/user write buffer pointer 

mov 

word ptr WRBOFPTR+2,0 

/upper half 

mov 

word ptr WRPKTID,0 


mov 

word ptr WRPKTID+2,0 

/write packet id = 0 


f 

; do sign on message (INIT executes in ring three) 


push 

stdout 

push 

ds 

push 

offset ds:Idln 

push 

Idln_len 

push 

ds 

push 

offset ds:wlen 

call 

DosWrite 

mov 

retf 

word ptr es:[bx+3],OlOOh 


page 
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Open PIPEIN$ (section 6.5.1.2) 


Openln: push 

es 


push 

bx 

/save req packet ptr on stack 

cmp 

WRCLOSE, 1 

je 

OWaitl 

/hold write opens until EOF 
/sent to reader 

mov 

al,LocallnfoSeg 


mov 

dl, GetDOSVar 


call 

[DEVHELP] 

/get pointer to DOSVar # 2 
/DOSVar #2 is ptr to local INFO seg 

mov 

es, ax 

les 

bx,es:[bx] 

/get pointer to local info seg 

mov 

cx,es:[bx] 

/put current process id in cx 

cmp 

PINPID,-1 

/-I = device unowned 

je 

OpenOkl 

/jump if unowned 

cmp 

ax, cx 

/test for open from current owner 

jne 

OWaitl 

/jump if not from current owner 

inc 

PINOCT 

/add one to open count 

jmp 

Oexitl 


OpenOkl 

mov 

PINPID,cx 

/save new owner id 


mov 

PINOCT,1 

/new owner 

Oexitl: 

pop 

bx 



pop 

es 

/restore req packet ptr 


mov 

word ptr es:[bx+3],100h 

/set status to OK 


retf 




OWaitl: pop 

bx 


pop 

es 

/restore req packet ptr 

OiWait: mov 

si,offset PINOPENQ 

mov 

dl,PushRequest 


call 

[DEVHELP] 

/put open packet on queue 

mov 

ax,es 

/upper addr of packet 

mov 

cx,Offffh 


mov 

di,Offffh 

/no timeout 

mov 

dh, 0 

/sleep is interruptable 

mov 

dl,ProcBlock 

/block until device available 

call 

[DEVHELP] 


jc 

BadWkUp2 

/carry flag set if unusual wakeup 

mov 

dl,PullParticular 

/es:bx already set 
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call 

jc 

[DEVHELP] 

OiGone 

/C flag set if packet not there 
/jump if valid wakeup 

jmp 

OiWait 

/packet still there, queue again 
/this wakeup not from Reader 

OiGone: jmp 

Openln 

/try to own device now 

BadWkUp2: 

mov 

es:[bx+3],8111h 

/status = I/O Interrrupted 

retf 




page 

; Write to PIPEIN$ (section 6.5.1.3) 


WriteIn: 


push 

es 

push 

bx 

mov 

ax,es:[bx+18] 

mov 

WRBUFSIZ,ax 

mov 

al,LocallnfoSeg 

mov 

dl,GetDOSVar 

call 

[DEVHELP] 

mov 

es, ax 

les 

bx,es:[bx] 

mov 

cx,es:[bx] 

cmp 

PINPID,cx 

jz 

Getseml 

pop 

bx 

pop 

es 

mov 

es:[bx+3],810ch 

retf 

i 


;save req packet ptr 
/request packet buffer size 
;save in local variable 


/get pointer to DOSVar # 2 
/DOSVar #2 is ptr to local INFO seg 

/get pointer to local info seg 
/put requesting pid into cx 
/is this the current owner ? 


/requesting pid not the owner 
/set status = general failure 


Getseml: 

pop bp 

pop es 

mov bx,offset WRRAMSEM 

mov ax, ds 

mov cx,Offffh 

mov di. Off ffh /no timeout 
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mov 

dl, SemRequest 

call 

[DEVHELP] 

jnc 

DoWr 

mov 

bx,bp 

mov 

es:[bx+3],8111h 

retf 



DoWr: 



push 

es 


push 

bp 


mov 

ax,es:[bp+16] 


mov 

bx,es:[bp+14] 


mov 

cx,WRBUFSIZ 


mov 

dh, 1 


mov 

dl, PhysToUVirt 


call 

[DEVHELP] 


mov 

bp,bx 


jnc 

WrCont 


pop 

bx 


pop 

es 


mov 

retf 

es:[bx+3],810ch 

WrCont: 

mov 

WRCTR, 0 


mov 

WRBLCTR, 0 

WrLoop: 

mov 

di,WRCTR 


cmp 

WRBUFSIZ, di 


jne 

WrOne 


mov 

ax, es 

mov 

dh, 2 

mov 

dl,PhysToUVirt 

call 

[DEVHELP] 

mov 

bx,offset WRRAMSEM 

mov 

ax, ds 

mov 

dl,SemClear 

call 

[DEVHELP] 

mov 

ax,word ptr RDPKTID 

or 

ax,word ptr RDPKTID+2 

je 

WrEnd 


;get Write Ram Semaphore or WAIT 
;jump if we got semaphore 

/error getting semaphore 
/set status = I/O Interrupted 


/save req pkt id 

/hi physical addr of user buffer 
/lo physical addr of user buffer 

/memory readable/writeable 

/get virtual address 

/result in es:bx 

/use bp as base reg for xfer 

/jump if no error in conversion 


/set status to failure 


/initialize write counters 


/jump if counter not equal to 
/buffer size 


/done with this write req 

/put selector into ax 

/release virtual address selector 


/release write semaphore 


/test for zero, no one waiting 
/jump if no read waiting 
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mov 

mov 

mov 

call 

bx,word ptr RDPKTID 
ax,word ptr RDPKTID+2 
dl,ProcRun 
[DEVHELP] 

;run current waiting read 


mov 

mov 

word ptr RDPKTID,0 
word ptr RDPKTID+2,0 


WrEnd: 

pop 

pop 

mov 

retf 

bx 

es 

word ptr es:[bx+3],lOOh 

/restore req pkt id 
;set status = OK 

WrOne: 

mov 

mov 

mov 

call 

jc 

al,byte ptr es:[bp][di] 
bx,offset CHARQ 
dl,QueueWrite 
[DEVHELP] 

BlockWr 

;get char from user buffer 

/write char onto queue 
/block write thread if Q full 


inc 

inc 

jmp 

WRCTR 

WRBLCTR 

WrLoop 

/increment counters 
/do it again 

BlockWr 

cmp 

j e 

WRBLCTR, 0 

BlockWrl 

/don't unblock if no chars written 


mov 

or 

je 

ax,word ptr RDPKTID 
ax,word ptr RDPKTID+2 
BlockWrl 

/test for zero, no one waiting 
/don't bother if no read waiting 


mov 

mov 

mov 

call 

bx,word ptr RDPKTID 
ax,word ptr RDPKTID+2 
dl,ProcRun 
[DEVHELP] 

/run waiting read if chars written 


mov 

mov 

word ptr RDPKTID, 0 
word ptr RDPKTID+2,0 


BlockWrl: 

pop 

pop 

mov 

mov 

mov 

mov 

bx 

si 

word ptr WRPKTID,bx 
word ptr WRPKTID+2,si 
ax, si 

WRBLCTR, 0 

/save id for reader to run 

/event high address for block 
/reset chars written after block 
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mov cx,Offffh 

mov di,Offffh 

mov dh, 0 

mov dl,ProcBlock 

call [DEVHELP] 

jc BadWkUpl 

push si 

push bx 

jmp WrLoop 


BadWkUpl: 

push si 

mov ax,es 

mov dh, 2 

mov dl, PhysToUVirt 

call [DEVHELP] 

push bx 

mov bx,offset WRRAMSEM 

mov ax,ds 

mov dl,SemClear 

call [DEVHELP] 

pop bx 

pop es 

mov es:[bx+3],8111h 

retf 


;no timeout 
;interruptable sleep 


;jump if unusual wakeup 

/restore req pkt id to stack 
/back to the writing game 


/save write req pkt selector 
/put buffer selector into ax 
/release virtual address selector 


/save write req pkt offset 


/release write semaphore 


/restore upper req pkt id to es 
/set status = I/O interrupted 
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Read from PIPEIN$ (section 6.5.1.4) 


Readln: /Device PIPEIN$ is write only 

/should read from PIPEOUT$ 


push 

es 



push 

bx 



mov 

al,LocallnfoSeg 



mov 

dl,GetDOSVar 



call 

[DEVHELP] 

/get pointer to DOSVar # 2 
/DOSVar #2 is ptr to local 

info seg 

mov 

es, ax 



les 

bx,es:[bx] 

/get pointer to local info 

seg 
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mov 

cx,es:[bx] 

cmp 

PINPID,cx 

je 

RdFault 

pop 

bx 

pop 

es 

mov 

retf 

es:[bx+3],810ch 


RdFault: 


pop 

bx 

pop 

es 

mov 

es:[bx+3],810bh 

retf 



;first word is requesting pid 
/check if requestor is owner 
;jump if it is 

/not owner, general failure 

/set status = general failure 


/shouldn't issue read to 
/write end of PIPER 
/set status = read fault 
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Close PIPEIN$ device (section 6.5.1.5) 


Closeln: 


push 

es 

push 

bx 

mov 

al,LocallnfoSeg 

mov 

dl, GetDOSVar 

call 

[DEVHELP] 

mov 

es,ax 

les 

bx,es:[bx] 

mov 

cx,es:[bx] 

cmp 

PINPID,cx 

jz 

Getsem2 

pop 

bx 

pop 

es 

mov 

es:[bx+3],810Ch 

retf 



Getsem2: 


pop 

si 

pop 

es 

mov 

bx,Offset WRRAMSEM 

mov 

ax, ds 

mov 

cx,Offffh 

mov 

di,Offffh 

mov 

dl, SemRequest 

call 

[DEVHELP] 


/save req packet ptr on stack 

/get pointer to DOSVar # 2 
/DOSVar #2 is ptr to local info seg 

/get pointer to local info seg 

/check if this pid is current owner 

/cannot close if not owner 
/set status to general failure 

/si will hold bx value from 
/request packet 

/setup address of ram semaphore 
/no timeout 

/get Write Ram Semaphore or WAIT 



452 WRITING OS/2 DEVICE DRIVERS 


mov 

bx, si 

jnc 

ChkOctl 

mov 

es:[bx+3],8111h 

retf 


ChkOctl: 


push 

es 

push 

bx 

mov 

bx,offset WRRAMSEM 

mov 

ax, ds 

mov 

dl,SemClear 

call 

[DEVHELP] 

dec 

PINOCT 

jz 

DoClIn 

pop 

bx 

pop 

es 

mov 

word ptr es:[bx+3],100h 

retf 


DoClIn: mov 

PINPID,-1 

cmp 

POUTPID,-1 

jnz 

EndClIn 

cmp 

CHARQ.Qcount,0 

jz 

DeQClIn 

/ got here if 

reader is owned or char Q 


EndClIn: 


mov 

WRCLOSE,1 

mov 

ax,word ptr RDPKTID 

or 

ax,word ptr RDPKTID+2 

jz 

ByeClIn 

mov 

bx,word ptr RDPKTID 

mov 

ax,word ptr RDPKTID+2 

mov 

dl,ProcRun 

call 

[DEVHELP] 

mov 

word ptr RDPKTID,0 

mov 

word ptr RDPKTID+2,0 

ByeClIn: 


pop 

bx 

pop 

es 

mov 

word ptr es:[bx+3],lOOh 

retf 



/restore request packet id value 
;jump if we got semaphore 

/set status = I/O Interrupted 

/save req pkt id 

/ax:bx has write semaphore 

/release semaphore 

/this pid is owner, allow close 
/do final close if Open Count = 0 

/set status = OK 

/set PINPID = -1 (unowned) 

/check if Read device is owned 

/if owned set WRCLOSE flag 

/jump if char Q empty 

not empty 

/set write close flag and leave 


/run waiting read process 
/this packet no longer waiting 
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; got here if no reader owners and char Q was empty 

/ 

; this code de-queues all write device open packets and runs them 
DeQClIn: 


mov 

si,offset PINOPENQ 

;es:bx already set 

mov 

dl,PullRequest 


call 

[DEVHELP] 


jc 

ByeClIn 

/leave when queue empty 

mov 

ax, es 


mov 

dl,ProcRun 


call 

[DEVHELP] 


jmp 

DeQClIn 
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; Initialize PIPEOUT$ (section 6.5.2.1) 


InitOut: 


mov 

ax,es:[bx+14] ; 

get DevHelp offset 

mov 

word ptr DEVHELP,ax 


mov 

ax,es:[bx+16] ; 

get DevHelp segment 

mov 

word ptr DEVHELP+2,ax 


put end of 

code and data segments back into request packet 

mov 

word ptr es:[bx+14],offset 

_TEXT:TextEnd 

mov 

word ptr es:[bx+16],offset 

DGROUP:DgrpEnd 


initialize 

Read variables 



mov 

POUTPID, -1 

/current write owner process id 

mov 

word ptr POUTOPENQ,0 

/pointer to open 

request queue 

mov 

word ptr P0UT0PENQ+2,0 

/upper half 


mov 

POUTOCT,0 

/read open count 

(same owner) 

mov 

word ptr RDRAMSEM,0 

/read semaphore „ 


mov 

word ptr RDRAMSEM+2,0 

/upper half 
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mov 

RDCTR, 0 

/read counter (bytes read) 

mov 

RDBUFSIZ,0 

/user write buffer size 

mov 

word ptr RDBUFPTR,0 

/user write buffer pointer 

mov 

word ptr RDBUFPTR+2,0 

/upper half 

mov 

word ptr RDPKTID,0 


mov 

word ptr RDPKTID+2,0 

/read packet id = 0 


sign on 

message (INIT packet done in ring three) 

push 

stdout 

push 

ds 

push 

offset ds:IdOut 

push 

IdOut_len 

push 

ds 

push 

offset wlen 

call 

DosWrite 


mov word ptr es:[bx+3],OlOOh 
retf 
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Open PIPEOUT$ (Section 6.5.2.2) 


OpenOut: 


push 

es 

push 

bx 

mov 

al,LocallnfoSeg 

mov 

dl,GetDOSVar 

call 

[DEVHELP] 

mov 

es, ax 

les 

bx,es:[bx] 

mov 

cx,es:[bx] 

cmp 

POUTPID,-1 

je 

0pen0k2 

cmp 

ax, cx 

jne 

0Wait2 

inc 

POUTOCT 

jmp 

0exit2 


/save req packet ptr on stack 


/get pointer to DOSVar # 2 
/DOSVar #2 is ptr to local info seg 

/get pointer to local info seg 
/put current process id in cx 
/-I = device unowned 
/jump if unowned 

/test for open from current owner 
/jump if not from current owner 
/add one to open count 


0pen0k2: 
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mov 

POUTPID,cx 

/save new owner id 

mov 

POUTOCT,1 

/new owner 

0exit2: pop 

bx 


pop 

es 

/restore req packet ptr 

mov 

word ptr es:[bx+3],10Oh 

/set status to OK 

retf 




OWait2: 

POP 

bx 



pop 

es 

/restore req packet ptr 

WaitO: 

mov 

mov 

si,offset POUTOPENQ 
dl,PushRequest 



call 

[DEVHELP] 

/put open packet on queue 


mov 

mov 

ax, es 
cx,Offffh 

/upper addr of packet to ax 


mov 

di,Offffh 

/no timeout 


mov 

dh, 0 

/sleep is interruptable 


mov 

call 

dl,ProcBlock 
[DEVHELP] 

/block until device available 


jo 

BadWkUp4 

/carry flag set if unusual wakeup 


mov 

dl,PullParticular 

/es:bx already set 


call 

[DEVHELP] 

/C flag set if packet not there 


jo 

GoneO 

/jump if valid wakeup 


jmp 

WaitO 

/packet still there, queue again 
/this wakeup not from Reader 

GoneO: 

jmp 

OpenOut 

/try to own device now 


BadWkUp4: 

mov es:[bx+3], 8111h /status = I/O Interrrupted 

retf 


page 

; Read from PIPEOUT$ (section 6.5.2.3) 

Readout: 

push es 

push bx /save req packet ptr on stack 

mov ax,es:[bx+18] /request packet buffer size 
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mov RDBUFSIZ,ax 

mov al,LocallnfoSeg 

mov dl, GetDOSVar 

call [DF.VHELP] 

mov es,ax 

les bx,es:[bx] 

mov cx,es:[bx] 

cmp POUTPID,cx 

jz Getsem3 


pop bx 

pop es 

mov word ptr es:[bx+18],0 

mov es:[bx+3],810ch 

retf 


Getsem3: 

pop bp 

pop es 

mov bx,offset RDRAMSEM 

mov ax,ds 

mov cx,Offffh 

mov di,Offffh 

mov dl,SemRequest 

call [DEVHELP] 

jnc DoRead 


mov bx,bp 

mov word ptr es:[bx+18],0 

mov es:[bx+3],8111h 

retf 


;save in local variable 


;get pointer to DOSVar # 2 
;DOSVar #2 is ptr to local info seg 

;get pointer to local info seg 
;put requesting pid into cx 
;is this the current owner ? 


/requesting pid not the owner 

/read count = 0 
/set status = general failure 


/hold pkt id offset in bp 


/no timeout 

/get Read Ram Semaphore or WAIT 
/jump if we got semaphore 


/restore packet id offset 
/read count = 0 
/set status = I/O Interrupted 


push 

es 


push 

bp 


mov 

ax,es:[bp+16] 

/hi physical addr of user buffer 

mov 

bx,es:[bp+14] 

/lo physical addr of user buffer 

mov 

cx,RDBUFSIZ 


mov 

dh, 1 

/memory readable/writeable 

mov 

dl,PhysToUVirt 

/get virtual address 

call 

[DEVHELP] 

/result in es:bx 

mov 

bp,bx 

/use bp as base reg for xfer 

jnc 

RdCont 

/jump if no error in conversion 
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RdCont: 
RdLoop: 


GotOne: 


RdDone: 


BlockRd 


pop bx 

pop es 

mov word ptr es:[bx+18],0 

mov es:[bx+3],810ch 

retf 


mov 

RDCTR, 0 

mov 

di,RDCTR 

mov 

bx,offset CHARQ 

mov 

dl,QueueRead 

call 

[DEVHELP] 

jnc 

GotOne 

cmp 

RDCTR, 0 

jne 

RdDone 

jmp 

BlockRd 


mov byte ptr es: [bp] [di],al 

inc di 

mov RDCTR, di 

cmp RDBUFSIZ, di 

jne RdLoop 


mov 

ax,word ptr 

WRPKTID 

or 

ax,word ptr 

WRPKTID+2 

je 

RdEnd 



mov bx,word ptr WRPKTID 

mov ax,word ptr WRPKTID+2 

mov dl,ProcRun 

call [DEVHELP] 

mov word ptr WRPKTID, 0 

mov word ptr WRPKTID+2,0 

jmp RdEnd 


cmp 

WRCLOSE,1 

je 

NoRdBlk 


pop 

bx 

pop 

si 


/read count = 0 

/set status to failure 


/initialize read counter 
/di used as index 

/read a char from queue 
/jump if queue not empty 

/done if any chars read 
/block if nothing read yet 

/put char into user buffer 


/jump if more to read 


/test for zero in write pkt id 
/jump if no write waiting 

/if not zero 

/write process waiting for 
/room in queue 

/run current waiting write 


/restore req pkt id to si:bx 
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mov 

word ptr RDPKTID,bx 

;save id for writer to run 

mov 

word ptr RDPKTID+2,si 


mov 

ax, si 

/event high address for block 

mov 

cx,Offffh 


mov 

di,Offffh 

;no timeout 

mov 

dh, 0 

;interruptable sleep 

mov 

dl,ProcBlock 


call 

[DEVHELP] 


jc 

BadWkUp3 

;jump if unusual wakeup 

push 

si 


push 

bx 

/restore req pkt id to stack 

jmp 

RdLoop 

/back to the reading game 

NoRdBlk: 

mov 

WRCLOSE ,0 


push 

es 

/save user buffer selector 

DeQWr: mov 

si,offset PINOPENQ 


mov 

dl,PullRequest 


call 

[DEVHELP] 

/pull all write open requests 

jc 

RdNearEnd 

/leave when queue empty 

mov 

ax, es 


mov 

dl,ProcRun 


call 

[DEVHELP] 

/run all waiting threads 

jmp 

DeQWr 



RdNearEnd: 

pop 

es 

/restore user buffer selector 

RdEnd: mov 

ax, es 

/put selector into ax 

mov 

dh, 2 

/release virtual address selector 

mov 

dl,PhysToUVirt 


call 

[DEVHELP] 


mov 

bx,offset RDRAMSEM 


mov 

ax, ds 


mov 

dl,SemClear 


call 

[DEVHELP] 

/release write semaphore 

pop 

bx 


pop 

es 

/restore req pkt id 

mov 

ax,RDCTR 


mov 

es:[bx+18],ax 

/set read count in packet 

mov 

word ptr es:[bx+3],lOOh 

/set status = OK 

retf 

BadWkUp3: 

push 

si 

/save selector of req pkt id 

mov 

ax, es 

/put selector into ax 

mov 

dh, 2 

/release virtual address selector 
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mov 

dl,PhysToUVirt 


call 

[DEVHELP] 


push 

bx 

;save offset of req pkt id 

mov 

bx,offset RDRAMSEM 


mov 

ax, ds 

;ax:bx has read semaphore 

mov 

dl,SemClear 


call 

[DEVHELP] 

/release semaphore 

pop 

bx / 

/restore complete req pkt id 

pop 

es 

mov 

ax,RDCTR 


mov 

es:[bx+18],ax 

/set read counter in packet 

mov 

retf 

es:[bx+3],8111h 

/set status = I/O interrupted 
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/ 

/ Write 

/ 

to PIPEIN$ (Section 6.5.2.4) 


WriteOut: 

/this device is read only 



/should issue writes to PIPEIN$ 

push 

es 


push 

bx 


mov 

al,LocallnfoSeg 


mov 

dl,GetDOSVar 


call 

[DEVHELP] 

/get pointer to DOSVar # 2 



/DOSVar #2 is ptr to local info 

mov 

es, ax 


les 

bx,es:[bx] 

/get pointer to local info seg 

mov 

cx,es:[bx] 

/first word is requesting pid 

cmp 

POUTPID,cx 

/check if requestor is owner 

je 

WrFault 

/jump if it is 

pop 

bx 

/not owner, general failure 

pop 

es 


mov 

es:[bx+3],810ch 

/set status = general failure 

retf 



WrFault: 



pop 

bx 

/shouldn't issue write to 

pop 

es 

/PIPEOUT$ 

mov 

es:[bx+3],810ah 

/set status = write fault 


retf 



460 


WRITING OS/2 DEVICE DRIVERS 


page 


Close PIPEOUT$ (Section 6.5.2.5) 


CloseOut: 


push 

es 


push 

bx 

/save req packet ptr on stack 

mov 

al,LocallnfoSeg 


mov 

dl,GetDOSVar 


call 

[DEVHELP] 

/get pointer to DOSVar # 2 
/DOSVar #2 is ptr to local info seg 

mov 

es, ax 


les 

bx,es:[bx] 

/get pointer to local info seg 

mov 

cx,es:[bx] 


cmp 

POUTPID,cx 

/check if this pid is current owner 

j* 

Getsem4 


pop 

bx 

/cannot close if not owner 

pop 

es 


mov 

retf 

es:[bx+3],810Ch 

/set status to general failure 


Getsem4: 

pop si 

pop es 

mov bx,offset RDRAMSEM 

mov ax,ds 

mov cx,Offffh 

mov di,Offffh 

mov dl,SemRequest 

call [DEVHELP] 

mov bx,si 

jnc ChkOct2 

mov es:[bx+3],8111h 

retf 

ChkOct2: 

push es 

push bx 

mov bx,offset RDRAMSEM 

mov ax,ds 

mov dl,SemClear 

call [DEVHELP] 


;save offset of req pkt id 

;ax:bx has read semaphore 
/release semaphore 


;si will hold bx value from 
/request packet 

/setup address of ram semaphore 
/no timeout 

/get Read Ram Semaphore or WAIT 
/restore request packet id value 
/jump if we got semaphore 

/set status =1/0 Interrupted 
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dec 

POUTOCT 

/this pid is owner, allow close 

jz 

DoClOut 

;do final close if Open Count = 

pop 

bx 


pop 

es 


mov 

word ptr es:[bx+3],lOOh 

/set status = OK 

retf 



DoClOut: 



mov 

POUTPID,-1 

/set POUTID = -1 (unowned) 

cmp 

WRCLOSE,0 

/test for write closed 

je 

DeQOut 

/jump, nothing coming soon 

mov 

WRCLOSE,0 

/reset flag 

DeQIn: mov 

si,offset PINOPENQ 

/es:bx already set 

mov 

dl,PullRequest 


call 

[DEVHELP] 


jc 

DeQOut 

/leave when queue empty 

mov 

ax, es 


mov 

dl,ProcRun 


call 

[DEVHELP] 


jmp 

DeQIn 


DeQOut: mov 

si,offset POUTOPENQ 

/es:bx already set 

mov 

dl,PullRequest 


call 

[DEVHELP] 


jc 

ByeClOut 

/leave when queue empty 

mov 

ax, es 


mov 

dl,ProcRun 


call 

[DEVHELP] 


jmp 

DeQOut 



ByeClOut: 

pop bx 

pop es 

mov word ptr es: [bx+3] ,10Oh 

retf 


TextEnd: 
_TEXT ends 
end 


PEPER.DEF 


LIBRARY 
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PIPER.CMD 


masm /Zi piper.asm,piper.obj,piper.1st; 
link /MRP piper.obj,piper.sys,,os2,piper.def 
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SAMPLE PROGRAMS/TIMDMP 


This appendix contains the programs described in Section 6.6. 

TIMDMP.DEF 


PAGE , i32 

TITLE Physical Memory Dump Device Driver for OS/2 
.286 /Enable PUSHA, POPA instructions 
; FILE : TIMDMP. ASM 
; Sample Device Driver for OS/2 

; Dumps physical memory to user-provided buffer. 

9 

; entry: ES:BX has pointer to packet 
; DS has main data segment of device driver 


; devices supported : TIMDMP$ 

/ 

; command packets are INIT and IOCtl 

; if device is busy, IOCtl packet is queued to STRATQ 

; IOCtl strategy routine starts timer and blocks 

; timer routine performs dump operation and unblocks strategy 

; strategy routine awakens next request on STRATQ 
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464 


WRITING OS/2 DEVICE DRIVERS 


stdin 

equ 

0 

stdout 

equ 

1 

stderr 

equ 

2 

cr 

equ 

Odh 

If 

equ 

Oah 


DevHelp Function Codes 


/ 

/ProcBlock 

equ 

04h 

/ProcRun 

equ 

05h 

/ PushRequest 

equ 

09h 

/PullRequest 

equ 

Oah 

/PullParticular 

equ 

Obh 

/VerifyAccess 

equ 

27h 

/ Lock 

equ 

13h 

/VirtToPhys 

equ 

16h 

/Unlock 

equ 

14h 

/TickCount 

equ 

33h 

/ResetTimer 

equ 

lEh 

/PhysToVirt 

equ 

15h 

/UnPhysToVirt 

equ 

32h 

/GetDOSVar 

equ 

24h 

/GloballnfoSeg 

equ 

Olh 


ProcBlock 


mov 

bx,EventIdLow 

/for this example use 

strategy 

mov 

ax,EventIdHigh 

/packet address es:bx 


mov 

cx,TimeoutLow 

/in milliseconds 


mov 

di,TimeoutHigh 

/-I waits forever 


mov 

mov 

call 

dh,InterruptableFlag 
dl,ProcBlock 
[DEVHELP] 

/C flag set if unusual 

wakeup 


;Z flag set if timeout 
;AL awake code, non-zero for 
/unusual wakeup 
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; ProcRun 


mov 

bx,EventIdLow 

;for this example use strategy 

mov 

ax,EventldHigh 

/packet address es:bx 

mov 

dl,ProcRun 


call 

[DEVHELP] 



PushRequest 


mov 

si,offset queue 

;ds points to main data segment 
/pointer to head of device list 

les 

bx,RequestPacket 

/pointer to device RequestPacket 

mov 

dl,PushRequest 


call 

[DEVHELP] 


guest 

mov 

si,offset queue 

/ds points to main data segment 
/pointer to head of device list 

mov 

dl,PullRequest 


call 

[DEVHELP] 



;C flag clear if no error 
;es:bx points to device packet 
;C flag set if no packet 


;PullParticular 


;ds points to main data segment 


; 

mov 

si,offset queue 

/pointer to head of device list 

/ 

les 

bx,RequestPacket 

/pointer to device RequestPacket 

; 

mov 

dl,PullParticular 


/ 

call 

[DEVHELP] 



;C flag clear if no error 
;C flag set if no packet found 


; Ver i f yAcce s s 


/ 

mov 

ax,UserSelector 

/selector of user segment 

/ 

mov 

di,UserOffset 

/offset within user segment 

/ 

mov 

cx,Length 

/length of region 

/ 

mov 

dh,Rights 

/0=read only, l=read/write 

/ 

mov 

dl,VerifyAccess 


/ 

/ 

call 

[DEVHELP] 

/C flag clear if no error 
/C bit set if access violation 
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r 

/ 

; Lock 

; mov 

ax,UserSelector 

/Selector of segment to be locked 

; mov 

bh,type 

;O=short-term lock 

; mov 

bl,wait 

;l=wait until lock is accomplished 

; mov 

dl,Lock 


; call 

/ 

[DEVHLP] 

;C clear, AX:BX=lock handle 

/ 

;VirtToPhys 

/ Ids 

si, Virtual 

;ds:si = virtual address to convert 

; mov 

dl,VirtToPhys 

;to physical address 

; call 

[DEVHLP] 

/Note ds has been changed 

' 


/C clear, AX:BX=physical address 

9 

9 

;Unlock 

; mov 

ax,HighHandle 

/lock handle returned by Lock 

; mov 

bx,LowHandle 


/ mov 

dl,Unlock 


; call 

/ 

[DEVHLP] 


/ 

/ 

;TickCount 

; mov 

ax,TimerEntry 

/Offset of timer entry point in 

; 


/main code segment 

; mov 

bx,count 

/number of ticks before activation 

; mov 

dl,TickCount 


; call 

r 

[DEVHLP] 


9 

; ResetTimer 

/ mov 

ax,TimerEntry 

/Offset of timer entry point in 

r 


/main code segment 

; mov 

dl,ResetTimer 


; call 

9 

[DEVHLP] 


9 

9 

;PhysToVirt 

; mov 

ax,HighPhys 

/AX:BX = physical address 

/ mov 

bx,LowPhys 


; mov 

cx,LenPhys 

/CX = length of segment 

; mov 

dh, Map Where 

/0=ds:si, l=es:di 

; mov 

dl, PhysToVirt 
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call [DEVHLP] 


;ds must be main data segment 
;at first call to PhysToVirt 


;UnPhysToVirt 

; mov dl,UnPhysToVirt 

; call [DEVHLP] ;es not preserved 


; GetDOSVar 

/ mov al,VarNumber ;1-GlobalInfoSeg 

; mov dl, GetDOSVar 

; call [DEVHELP] ;C flag cleared if no error 

/ax:bx=bimodal pointer to variable 


GloballnfoSeg 


STRUCT 


TimelnSecs 

DD 

? 

;Time since 1/1/70 in seconds 

Bootms 

DD 

o 

/Time since boot in ms. 

TODHr 

DB 

? 

/Time of day - Hour 

TODMin 

DB 

? 

/ - Minutes 

TODSecs 

DB 

? 

/ - Seconds 

TODHunds 

DB 

o 

/ - .01 seconds 

Timezone 

DW 

? 

/Timezone in minutes 

Ticklnterval 

DW 

•? 

/Clock tick interval in .1 ms 
/THIS FIELD IS USED IN TIMDMP 

Day 

DB 

o 

/Day of month 

Month 

DB 

o 

/Month of Year 

Year 

DW 

o 

/Year (80=1980, 0=2000, 79=2079) 

WeekDay 

DB 

o 

/Day of Week 

Major 

DB 

o 

/Major Version # 

Minor 

DB 

o 

/Minor Version # 

Revision 

DB 

? 

/Revision Letter 

CurrentSG 

DB 

? 

/Current screen group 

MaxSG 

DB 

o 

/Number of screen groups (max) 

HugeShift 

DB 

? 

/Shift count for huge segments (4) 

ProtOnly 

DB 

? 

/Protect-Only flag 

PID 

DW 

? 

/Process ID of foreground process 

Dynamic 

DB 

? 

/Is dynamic variation enabled? 

MaxWait 

DB 

? 

/Maximum wait period in seconds 

MinSlice 

DW 

? 

/Minimum time slice in ms. 

MaxSlice 

DW 

? 

/Maximum time slice in ms. 
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; Boot 

DW ? 

;Boot drive 

; GloballnfoSeg 


ENDS 

PARAMETER 

STRUC 

/Format of IOCtl Parameter Buffer 

PAUSE 

DW ? 

/Time to wait in seconds 

START 

DD ? 

/Starting address in physical memory of 
/memory to be copied into data buffer 

DUMPSIZE 

DW ? 

/Size of memory to be dumped in bytes 

PARAMETER 

ENDS 


PACKETHDR 

STRUC 

/Header of INIT and IOCtl strategy packets 

PKTLENGTH 

DB ? 

/Packet Length 

UNIT 

DB ? 

/Unit, unused for character drivers 

COMMAND 

DB ? 

/Command code, 0=INIT, 10h=IOCtl 

STATUS 

DW ? 

/Status word 

PKTRESERVED 

DD ? 


PTKLINKAGE 

DD ? 


PACKETHDR 

ENDS 


INITIN 

STRUC 

/Format of INIT packet at strategy entry 

INITINHDR 

DB SIZE 

PACKETHDR DUP (?) 

INITSKIP 

DB ? 


HELPER 

DD ? 

/Address of device helper interface 

INITIN 

ENDS 


INITOUT 

STRUC 

/Format of INIT packet as returned by driver 

INITOUTHDR 

DB SIZE 

PACKETHDR DUP (?) 

UNITCOUNT 

DB ? 

/0 for character devices 

CODEOFFSET 

DW ? 

/Length of main code segment 

DATAOFFSET 

DW ? 

/Length of main data segment 

INITOUT 

ENDS 


DUMPPACKET 

STRUC 

/Format of IOCtl buffer 

DUMPHDR 

DB SIZE 

PACKETHDR DUP (?) 

CATEGORY 

DB ? 

/Category is 80h 

FUNCTION 

DB ? 

/Function is 0 

PBUFFER 

DD ? 

/Virtual address of Parameter Buffer 

DBUFFER 

DD ? 

/Virtual address of Data Buffer 

DUMPPACKET 

ENDS 


TDCATEGORY 

EQU 8Oh 


TDCODE 

EQU 0 



DATASE6 SEGMENT ' DATA' 
DD -1 


;no other driver headers 
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DW 80C0h 
DW ENTRY 
DW 0 

DB "TIMDMP$ " 
DB 8 DUP (0) 


;Generic IOCtl driver 
;strategy entry point 
;no IDC 

;name of driver 
;Reserved 


CURRPACKET 

DD 

0 

/Driver is idle 

STRATQ 

DD 

0 

/No packets on strategy queue 

PHYSICALADDRESS 

DD 0 

/Physical address to be dumped 

PHYSICALSIZE 

DW 

0 

/Size of physical memory to be dumped 

WAKEFLAG 

DW 

0 

/Was driver awakened by interrupt routine? 

DEVHLP 

DD 

0 

/Address of device helper routine 

LOCKHANDLE 

DD 

0 

/Lock handle for data buffer 

DPHYSICAL 

DD 

0 

/Physical address of data buffer 


INITMSG DB 'TIMDMP$ is loaded',cr,If 
MSGLEN DW MSGLEN-INITMSG 


DATAEND LABEL BYTE 
DATASEG ENDS 

EXTRN DOSWRITE: FAR 

CODESEG SEGMENT 'CODE' 

ASSUME DS:DATASEG,CS:CODESEG 

;INIT packet? 

;IOCtl packet? 
/unknown command 


ENTRY: 

CMP ES:[BX].COMMAND,0 
JE INIT 

CMP ES:[BX].COMMAND,lOh 
JE IOCtl 

MOV ES:[BX].STATUS,8103h 
RETF 


Initialization (section 6.6.1) 


INIT: 

MOV AX,WORD PTR ES:[BX].HELPER /Save address of DevHlp routine 

MOV WORD PTR DEVHLP,AX 

MOV AX,WORD PTR ES:[BX].HELPER+2 

MOV WORD PTR DEVHLP+2,AX 

MOV AX, stdout 
PUSH AX 
PUSH DS 

MOV AX,OFFSET INITMSG 
PUSH AX 
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PUSH MS6LGN 
PUSH DS 

MOV AX,OFFSET MSGLEN . 

PUSH AX 
CALL DOSWRITE 

DOSWRITE (stdout, INITMSG, MSGLEN, &MSGLEN) ; 

MOV BYTE PTR ES:[BX].UNITCOUNT,0 ;No units for character device 

;Set length of code, data segments 

MOV WORD PTR ES:[BX].CODEOFFSET,OFFSET CODEEND 

MOV WORD PTR ES:[BX].DATAOFFSET,OFFSET DATAEND 

MOV WORD PTR ES:[BX].STATUS,10Oh ;No error 

RETF 


Service IOCtl Packet (section 6.6.2) 


IOCtl: 

CMP ES:[BX].CATEGORY,TDCATEGORY 
JE CHKCODE 

MOV ES:[BX].STATUS,8103h 
RETF 
CHKCODE: 

CMP ES:[BX].FUNCTION,TDCODE 
JE GETONLINE 

MOV ES:[BX].STATUS,8103h 
RETF 


;Is this TimDmp Category 
/Error, bad category 

;Is this Dump Memory subcode? 
/Error, bad code 


GETONLINE: 

CLI 

MOV AX,WORD PTR CURRPACKET /Is driver currently idle? 

OR AX,WORD PTR CURRPACKET+2 

JE DRIVERIDLE 


MOV 

SI,OFFSET STRATQ 

MOV 

DL, 9 

CALL 

[DEVHLP] 

BLOCKREQUEST: 

MOV 

AX, ES 

MOV 

DL, 4 

CALL 

[DEVHLP] 

CLI 


MOV 

AX,WORD PTR CURRPACKET 

OR 

AX,WORD PTR CURRPACKET+2 

JNE 

BLOCKREQUEST 

MOV 

DL,OBh 


/PushReqPacket 

/Block on strategy packet address 
/Block 

/If CURRPACKET is non-zero, 

/this was accidental wakeup 

/PullParticular 
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CALL [DEVHLP] 

DRIVERIDLE: 

STI 

MOV WORD PTR CURRPACKET,BX 

MOV WORD PTR CDRRPACKET+2,ES 


VERIFYGIVEN: 


MOV 

DI, BX 

MOV 

BH, 0 

MOV 

BL, 0 

MOV 

DL,13h 

CALL 

[DEVHLP] 

MOV 

WORD PTR LOCKHANDLE,BX 

MOV 

WORD PTR LOCKHANDLE+2,AX 

PUSH 

DS 

LDS 

SI,ES:[DI].DBUFFER 

POP 

ES 

MOV 

DL,16h 

ASSUME 

ES: DATASEG 

CALL 

ES:[DEVHLP] 

ASSUME 

ES:NOTHING 

PUSH 

ES 

POP 

DS 


;Mark driver busy 


/Selector of param buffer 
/Offset in segment of param buffer 
/Segment length 
/Write access desired 
/VerifyAccess 

/Memory is accessable 
/Error, memory inaccessable 


/Selector of data buffer 

/Offset into segment of data buffer 


/Segment length 

/Write access desired 
/ Ver if yAcces s 

/Memory is accessable 
/Error, memory inaccessable 


/Save BX 

/Short-term lock 
/Wait for lock 
/ Lock 

/Save lock handle for Unlock 


/data buffer address to physical 
/ES points to main data segment 
/VirtToPhys 


/Restore DS to main data segment 


VERIFYPBUFFER: 

MOV AX,WORD PTR ES:[BX].PBUFFER+2 

MOV DI,WORD PTR ES:[BX].PBUFFER 

MOV CX,SIZE PARAMETER 

MOV DH,1 

MOV DL,27h 

CALL [DEVHLP] 

JNC VERIFYDBUFFER 

MOV WORD PTR ES:[BX].STATUS,810Ch 
RETF 

VERIFYDBUFFER: 

MOV AX, WORD PTR ES : [BX] . DBUFFER+2 

MOV DI,WORD PTR ES:[BX].DBUFFER 

PUSH DS 

LDS SI,ES:[BX].PBUFFER 

MOV CX,WORD PTR [SI].DUMPSIZE 

POP DS 

MOV DH,1 

MOV DL,27h 

CALL [DEVHLP] 

JNC VERIFYGIVEN 

MOV WORD PTR ES: [BX] . STATUS, 810Ch 

RETF 
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MOV 

WORD PTR DPHYSICAL,BX 

/Store data buffer physical address 

MOV 

WORD PTR DPHYSICAL+2,AX 

MOV 

AL, 1 

/Get address of global INFO segment 

MOV 

DL,24h 

/GetDOSVar 

CALL 

[DEVHLP] 


MOV 

ES, AX 

/ES:BX = Var#l returns: 

MOV 

ES,ES:[BX] 

/ES:BX = Ptr to global INFO segment 

XOR 

bx,bx 


MOV 

CX,WORD PTR ES:[14+BX] 

/Get tick interval in .1 ms. 

LES 

BX,CURRPACKET 

/ES:BX = IOCtl packet 

LES 

BX,ES:[BX].PBUFFER 

/ES:BX = Parameter buffer 

MOV 

AX,WORD PTR ES: [BX] .PAUSE 

/Get timeout interval in seconds 

MOV 

DX,10000 


MUL 

DX 

/Get timeout interval in .1 ms. 

DIV 

CX 

/Divide by tick interval in .1 ms. 

MOV 

CX,WORD PTR ES: [BX] .START 

/Get physical start address 

MOV 

WORD PTR PHYSICALADDRESS,CX 


MOV 

CX,WORD PTR ES:[BX].START+2 


MOV 

WORD PTR PHYSICALADDRESS+2,CX 


MOV 

CX,ES:[BX].DUMPSIZE 

/Get length of physical memory 

MOV 

PHYSICALSIZE,CX 


MOV 

BX, AX 

/Timeout interval in ticks 

OR 

BX, BX 

/Was time specified 0? 

JNE 

NOTZERO 


MOV 

BX, 1 

/Use 1 tick to wake up timer rtn 

NOTZERO: 

MOV 

AX,OFFSET TIMERENTRY 

/Entry point 

MOV 

DL,33H 

/Code for TickCount 

CLI 


/Have entered critical section 

CALL 

[DEVHLP] 


LES 

BX, CURRPACKET 

/Strategy packet address in ES:BX 

MOV 

DI,OFFFFh 

/No timeout 

MOV 

CX,OFFFFh 


MOV 

DH, 1 

/No interruption 

MOV 

DL, 4 

/Block 

MOV 

WAKEFLAG,0 


REBLOCK: 

MOV 

AX, ES 

/Strategy address is block key 

CALL 

[DEVHLP] 


CLI 


/Enter critical section 

CMP 

WAKEFLAG, 0 

/Were we awakened by timer 

JE 

REBLOCK 

/No, accidental wakeup 
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STI 


;Leave critical section 

PUSH 

BX 

;Save strategy packet address 

PUSH 

ES 


MOV 

SI,OFFSET STRATQ 

;Get waiting packet, if any 

MOV 

DL,OAh 

;PullReqPacket 

CALL 

[DEVHLP] 


JC 

NONEWAITING 


MOV 

DL, 9 

/Push back on request queue 

CALL 

[DEVHLP] 


MOV 

AX, ES 

/Unblock waiting request 

MOV 

DL, 5 

/Run 

CALL 

[DEVHLP] 


NONEWAITING: 

/Mark TIMDMP$ device available 

MOV 

WORD PTR CURRPACKET,0 

MOV 

WORD PTR CURRPACKET+2,0 


POP 

ES 

/Restore strategy packet address 

POP 

BX 


MOV 

RETF 

ES:[BX].STATUS,lOOh 

/Normal completion status 

; Timer entry point (section 6.6.3) 


TIMERENTRY: 

PUSHA 


/Save registers 

PUSH 

ES 


MOV 

BP, SP 

/Let BP -> DevHlp entry point 

PUSH 

WORD PTR [DEVHLP+2] 


PUSH 

WORD PTR [DEVHLP] 

/AX:BX = Address of memory to read 

MOV 

BX,WORD PTR PHYSICALADDRESS 

MOV 

AX,WORD PTR PHYSICALADDRESS+2 


PUSH 

AX 

/Save address for PhysToVirt 

PUSH 

BX 


PUSH 

WORD PTR DPHYSICAL+2 

/Save address of DBUFFER for later 

PUSH 

WORD PTR DPHYSICAL 


MOV 

CX,PHYSICALSIZE 

/CX = Length of segment 

MOV 

DH, 0 

/result in DS:SI 

MOV 

DL,15h 

/PhysToVirt 

CALL 

DWORD PTR SS:[BP-4] 

/Call DevHlp 

POP 

BX 

/Map user data buffer 

POP 

AX 


MOV 

DH, 1 

/result in ES:DI 

CALL 

DWORD PTR SS: [BP-4] 

/Call DevHlp 

POP 

BX 

/Get read address 

POP 

AX 


JNZ 

NOTRANS 

/Both addresses valid 

MOV 

DH, 0 

/result in DS:SI 
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CALL DWORD PTR SS:[BP-4] ;Call DevHlp 

NOTRANS: 

CLD 

REP MOVSB ; Copy bytes 

MOV DL,32h ;UnPhysToVirt 

CALL DWORD PTR SS:[BP-4] ;Call DevHlp 


; UnPhysToVirt restores DS-> main 
JNZ NOCHANGE 

STI 

NOCHANGE: 

MOV SP,BP 

MOV BX,WORD PTR LOCKHANDLE 

MOV AX,WORD PTR LOCKHANDLE+2 

MOV DL,14h 

CALL [DEVHLP] 

MOV AX,OFFSET TIMERENTRY 

MOV DL,lEh 

CALL [DEVHLP] 

MOV WAKEFLAG,1 

MOV BX,WORD PTR CURRPACKET 

MOV AX,WORD PTR CURRPACKET+2 

MOV DL, 5 

CALL [DEVHLP] 

POP ES 

POPA 

RETF 


data segment 

/Mode was not changed 
/Reenable interrupts 

/Restore stack 

/Get lock handle for Unlock 

/Unlock data buffer 

/ResetTimer 

/Mark strategy routine awake 
/Unblock strategy routine 

/Unblock 

/Restore registers (DS is OK) 


CODEEND: 
CODESEG ENDS 

END 
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n 


DUMP.C 


#include .h 

fdefine MAXBUFFER 4096 

unsigned far pascal DOSOPEN(); 
unsigned far pascal DOSDEVIOCTL(); 
unsigned far pascal DOSCLOSE(); 
unsigned far pascal DOSEXIT(); 

struct { 

unsigned pause; 
long start; 
unsigned dumpsize; 

} far pbuffer; 

unsigned char far dbuffer[MAXBUFFER]; 

unsigned dmphandle,action; 

main () 

{ 

int i; 

printf("TIMDMP$ test program\n"); 

printf("Enter base address (in hex) to be dumped: "); 
scanf("%lx",&(pbuffer.start)); 

printf("Enter number of bytes (in hex) to be dumped: "); 
scanf("%x",&(pbuffer.dumpsize)); 

printf("Enter number of seconds for timeout: "); 
scanf ("%d", &(pbuffer.pause)); 

DOSOPEN((char far *)"TIMDMP$", (char far *)&dmphandle, 
(char far *)fiaction,0L,0,1,0x42,0L); 

DOSDEVIOCTL((char far *) dbuffer, 

(char far *)Spbuffer,0,0x80,dmphandle); 

DOSCLOSE(dmphandle); 

printf("%.61X ",pbuffer.start); 

for (i=0;i<F0EU<R.dumpsize;i++) 

{ 

printf("%.2X ",dbuffer[i]); 
if (i%16 = 15 && i+l<F0EU<R.d\ampsize) 
printf("\n%.61x ",pbuffer.start+i+1); 

} 

printf("\n"); 

DOSEXIT(0,0) ; 

} 
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TIMDMP.DEF 


LIBRARY 

DUMP.DEF 


NAME dump WINDOWCOMPAT 

TIMDMP.CMD 


cl /c /AL dump.c 
link dump,,,,dump 
masm timdmp; 

link timdmp,timdmp.sys,,os2,timdmp 



APPENDIX H 


SAMPLE PROGRAMS/RAMDRVR 


This appendix contains programs described in Section 6.7. 


RAMDRV.ASM _ 

PAGE ,132 

TITLE Sample RAM Block Device Driver for OS/2 

.286P /allow SMSW instruction to get machine status word 

; FILE : RAMDRV.ASM 
/ 

; Sample Device Driver for. OS/2 

; Manages physical memory under file manager as a block device. 

; entry: ES:BX has pointer to packet 
; DS has main data segment of device driver 


; devices supported : RAMDRV logical unit numbers are assigned in boot order 


Command Packets: 
Init 

Media Check 

BuildBPB 

Read 

Write 

Removable 


- Initialize device 

- Return media status to file manager 

- Return BPB for device to file manager 

- Read sector(s) from device 

- Write sector(s) to device 

- File manager queries removable state of media 


477 




478 WRITING OS/2 DEVICE DRIVERS 


IOCtl - IOCtl packets used to format device 

Reset Media - File manager requests driver to reset media 

Partitionable - Return number of physical drives to file mgr 
Logical Map - Return logical unit map on physical drive 


st din 

equ 

0 

stdout 

equ 

1 

stderr 

equ 

2 

cr 

equ 

Odh 

If 

equ 

Oah 


DevHelp Function Codes 


AllocPhys 

equ 18h 


AttachDD 

equ 2Ah 


PhysToUVirt 

equ 17h 


; AllocPhys 



; mov 

ax,SizeHigh 

/size of physical region 

; mov 

bx,SizeLow 


; mov 

dh,Position 

;0=above 1 Meg, l=below 1 Meg 

; mov 

dl, AllocPhys 

; call 

f 

[DEVHELP] 


f 

; AttachDD 

/ 

; mov 

bx,offset DDName 

;ds:bx = address of driver name 

/ mov 

di,offset DDData 

;ds:di holds IDC data 

; mov 

dl,AttachDD 


; call 

/ 

[DEVHELP] 


/ 

; PhysToUVirt 

; mov 

ax,AddressHigh 


; mov 

bx,AddressLow 

/physical address 

; mov 

cx,Length 


/ mov 

dh,RequestType 

/0-get virt addr read/executable 

/ 


/1-get virt addr read/write 

/ 


/2-free virt addr 

; mov 

dl,PhysToUVirt 


; call 

/ 

[DEVHELP] 
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maindata segment 'DATA' 


DD 

DW 

DW 

DW 

DB 

DB 

DB 


-1 

80h 

BlockEntry 

0 

0 

7 DUP (0) 

8 DUP (0) 


;Block driver supports only one device driver 

/Block OS/2 driver 

/Entry point for strategy requests 

/No IDC support 

/Number of units (maintained by OS/2) 

/Balance of name field unused by block device 
/Reserved 


sectorsize equ 512 
clustersize equ 1 
reservedsize equ 1 


datasize 

noclusters 


fatsize 


equ 16 


/Sector size in bytes 

/number of sectors in allocation unit 
/number of reserved (boot) sectors 
/number of sectors in data area 
equ datasize/clustersize 

/number of clusters to represent data area 
nofatbytes equ (noclusters*3+l)/2+3 

/number of bytes to represent clusters in 
/12-bit FAT 

(nofatbytes+sectorsize-1)/sectorsize 

/number of sectors in FAT 
1 /number of sectors in root directory 


equ 


rootsize 
unitsize 


equ 


equ reservedsize+fatsize+rootsize+noclusters*clustersize 


tracksize equ 1 

/number of sectors in unit 
/number of sectors per track 

bpb DW 

sectorsize 1 

/Sector size 

DB 

clustersize 

/cluster size in sectors 

DW 

reservedsize 

/Reserved sectors 

DB 

1 

/l FAT 

DW 

(rootsize*sectorsize)/32 

DW 

unitsize 

/Number of root directory entries 
/Number of sectors in logical unit 

DB 

0F8h 

/(0 for extended BPB) 

/Media descriptor byte 

DW 

fatsize 

/FAT size in sectors (12-bit FAT) 

DW 

tracksize 

/sectors per track 

DW 

1 

/Number of heads 

DW 

0 

/hidden sectors 

DB 

12 DUP (?) 

/room for extended BPB 

DW 

unitsize/tracksize 


DB 

7 

/number of cylinders 
/device type (other) 

DW 

2 

/fixed media 

bpbnear 

dw offset bpb 

/physical base of allocated memory representing 

phase 

DD ? 


/ unit 
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OpenCount 

DW 

0 

changeflag 

DB 

OFFh 

resetflag 

DB 

0 

LockUnit 

DB 

0 

DevHlp 

DD 

? 

AttachName 

DB 

'STRAT$ ' 

AttachData 

label byte 

RealOff 

DW 

? 

RealCS 

DW 

? 

RealDS 

DW 

? 

ProtOff 

DW 

? 

ProtCS 

DW 

? 

ProtDS 

DW 

? 


JumpTable label byte 

DW 

, Init 

DW 

MediaCheck 

DW 

BuildBPB 

DW 

BadCommand 

DW 

Read 

DW 

BadCommand 

DW 

BadCommand 

DW 

BadCommand 

DW 

Write 

DW 

Write 

DW 

BadCommand 

DW 

BadCommand 

DW 

BadCommand 

DW 

BadCommand 

DW 

BadCommand 

DW 

Removable 

DW 

GenericIOCtl 

DW 

ResetMedia 

DW 

BadCommand 

DW 

BadCommand 

DW 

BadCommand 

DW 

BadCommand 

DW 

Partitionable 

DW 

LogicalUnitMa] 


/Count of unit opens (for Lock and Unlock) 

/flag media reset after generic IOCtl (format) 

/Unit is unlocked at start 

/Device Helper routine address, set at Init time 

/Attach to STRAT$ device 
/Place IDC calling data here 


dataend label byte 


initmsg db 
unitmsg db 
db 

addrmsg db 
db 

initlen dw 


'RAMDRV loaded 

':, Address ' 

6 dup (?) 
cr, If 

initlen-initmsg 


Unit 
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hexcode db '0123456789ABCDEF' 


maindata 

ends 




header 

STRUC 


/All strategy packets share this header format 


DB ? 




Unitcode 

DB ? 




Command 

DB ? 




Status 

DW ? 




Reserved 

DD ? 




Queue 

DD ? 




header 

ENDS 




initin 

STRUC 


; Format 

of INIT packet at strategy entry 


DB size 

DB ? 

header 

DUP (?) 


Helper 

DD ? 

DD ? 




BlockUnit 

DB ? 




initin 

ENDS 




initout 

STRUC 


;Driver 

returns data to INIT packet 


DB size 

header 

DUP (?) 


Units 

DB ? 




TextLen 

DW ? 




DataLen 

DW ? 




BPBarray 

DD ? 




initout 

ENDS 




build 

STRUC 


; Format 

of BUILD PBP strategy packet 


DB size 

header 

DUP (?) 


mediadesc 

DB ? 

DD ? 




BPBptr 

DD ? 




build 

ENDS 




check 

STRUC 


;Format 

of MEDIA CHECK packet 


DB size 

header 

DUP (?) 


checkdesc 

DB ? 




ChangeCode 

DB ? 




VolumeID 

DD ? 




check 

ENDS 




part 

STRUC 


; Format 

of PARTITIONABLE FIXED DISKS 

DB size 

header 

DUP (?) 


PartCount 

DB ? 



• 

part 

ENDS 




map 

STRUC 


; Format 

of GET LOGICAL MAP strategy packet 
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DB size header DUP (?) 
mapmask DB 4 DUP (?) 
map ENDS 

EO STRUC /Format of READ and WRITE strategy packets 

DB size header DUP (?) 

DB ? 

Transfer DD ? 

SectorCount DW ? 

SectorNumber DD ? 

10 ENDS 

IOCtl STRUC /Format of IOCtl packet 

DB size header DUP (?) 

Category DB ? 

Function DB ? 

Pbuffer DD ? 

Dbuffer DD ? 

IOCtl ENDS 1 

WriteTrack STRUC /Format of Parameter Buffer for WriteTrack IOCtl 

DB ? 

WriteHead DW (?) 

WriteCylinder DW (?) 

WriteFirst DW (?) 

WriteCount DW (?) 

WriteTrack ENDS 

extrn DosWrite:far 

maincode segment 'CODE' 

assume CS .-maincode, DS:maindata 


Strategy Entry (section 6.7.1.1) 


BlockEntry: 

mov AL,byte ptr ES:[BX].Command 

cmp al,17h 

jle CommandOK 

BadCommand: 

mov ES:[BX].Status,8103h 

retf 

CommandOK: 

xor AH, AH 

cmp AX, 0 

je Init 

add AX, AX 

DI, AX 


/Get command code 

/Within range of legal codes? 

/Unknown command code 


mov 
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smsw 

AX 


;Get Machine Status Word 

and 

AX, 1 


;Get real/prot flag 

jne 

ProtStrat 


;In protect mode 

mov 

bp, sp 



push 

RealCS 



push 

RealOff 



push 

ds 



mov 

ax,RealDS 



mov 

ds, ax 



call 

dword ptr 

[BP-4] 

;make IDC call 

pop 

ds 



push 

cs 


;JMP to command processing 

push 

word ptr JumpTable[DI] 

push 

bp 


/call strategy routine 

call 

dword ptr 

[BP-8] 

pop 

bp 



mov 

ax,RealDS 



mov 

ds, ax 



call 

dword ptr 

[BP-4] 

/make IDC call 

mov 

sp,bp 



retf 





ProtStrat: 


mov 

push 

push 

push 

mov 

mov 

call 

bp, sp 
ProtCS 
ProtOff 
ds 

ax,ProtDS 
ds, ax 
dword ptr 

[BP-4] 

/make 

IDC call 

pop 

push 

push 

ds 

cs 

word ptr JumpTable[DI] 

/JMP to command processing 

push 

call 

bp 

dword ptr 

[BP-8] 

/ call 

strategy routine 

pop 

mov 

mov 

call 

bp 

ax,ProtDS 
ds, ax 
dword ptr 

[BP-4] 

/make 

IDC call 

mov 

retf 

sp,bp 





Initialization (section 6.7.1.2) 


Init: 

mov AX,word ptr ES:[BX].Helper 

mov word ptr DevHlp,AX 

mov AX,word ptr ES:[BX].Helper+2 

mov word ptr DevHlp+2,AX 


;Save address of helper services 
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mov 

mov 

mov 

mov 


mov 

push 

push 

mov 

add 

mov 

mov 

mov 

mul 

mov 

mov 

mov 

mov 

call 

jc 

mov 

mov 

xor 

mov 

mov 

mov 

mov 

mov 

addrloop: 
std 
lodsb 
mov 
mov 
shr 
mov 
cld 
stosb 
mov 
and 
mov 
stosb 
loop 
mov 
push 
push 
push 
push 
push 


ES:[BX].TextLen,offset codeend ;Size of code segment 

ES:[BX].DataLen,offset dataend ;Size of data segment 

ES:[BX].Units,1 /Number of logical units 

word ptr ES:[BX].BPBarray,offset BPBnear 


word ptr ES:[BX].BPBarray+2,DS 

ES 

BX 

al,ES:[BX].BlockUnit 

al, 'A' 

unitmsg, al 

AX,unitsize 

DX,sectorsize 

DX 

BX, AX 
AX, DX 
DH, 0 
DL,18h 
[DevHlp] 

InitError 
word ptr phase,bx 
word ptr pbase+2,ax 
bx,bx 

si,offset pbase+2 
ax, ds 
es, ax 

di,offset addrmsg 
cx, 3 


ah,al 
bl, al 
bl, 4 

al,byte ptr hexcode[bx] 


bl, ah 
bl, Ofh 

al,byte ptr hexcode[bx] 

addrloop 
ax,stdout 
ax 
ds 

offset initmsg 

initlen 

ds 


/array of near pointer to BPB, 
/one per unit 


/Save req packet address for 
/return 

/Get unit number 


/get number of bytes in unit 


/AX:BX = number of bytes 
/Allocate from high memory 
/ AllocPhys 

/Allocation failed 
/Save for later use 


/Get address 


/3 byte address 

/get bytes in significance order 
/save for later 


/message address 
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mov 

ax,offset initlen 


push 

ax 


call 

DosWrite 


mov 

BX,offset AttachName 


mov 

DI,offset AttachData 


mov 

DL,2Ah 

;AttachDD 

call 

[DevHlp] 


pop 

bx 


pop 

es 


mov 

word ptr ES:[BX].Status,lOOh 

;Done, succes s 

retf 



InitError: 



pop 

bx 


mov 

word ptr ES: [BX] .TextLen,0 

/Reset segment lengths to 

mov 

word ptr ES:[BX].DataLen,0 


mov 

ES:[BX].Status,810Ch 

/Error - General Failure 

retf 



/ 

; BUILD 

BPB (section 6.7.1.3) 


BuildBPB: 



mov 

word ptr ES:[BX].BPBptr,offset bpb 



/Return pointer to BPB 

mov 

word ptr ES:[BX].BPBptr+2,ds 


mov 

ES:[BX].mediadesc,0F8h 

/media descriptor 

mov 

ES:[BX].Status,lOOh 

/Done, Success 


retf 

MEDIA CHECK (section 6.7.1.4) 


MediaCheck: 




mov 

ES:[BX].checkdesc,0F8h 

/media 

descriptor 

mov 

al,changeflag 



mov 

ES:[BX].ChangeCode, al 



mov 

ES:[BX].Status,lOOh 

/Done, 

success 

retf 





; RESET MEDIA (section 6.7.1.5) 

ResetMedia: 

cmp resetflag,0 

je noresetflag 

mov changeflag,1 
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mov resetflag,0 

noresetflag: 

mov ES:[BX].Status,lOOh /Done, success 

retf 


; REMOVABLE MEDIA (section 6.7.1.6) 

Removable: 

mov ES:[BX].Status,300h ;Non-removable 

retf 


; PARTITIONABLE FIXED DISKS (section 6.7.1.7) 

/ 

Partitionable: 

mov ES:[BX].PartCount,1 ;1 partition 

mov ES:[BX].Status,lOOh 

retf 


; LOGICAL UNIT MAP (section 6.7.1.8) 
/ 

LogicalUnitMap: 


mov 

byte ptr ES:[BX].mapmask,0 

;Set mask = 1 unit 

mov 

byte ptr ES:[BX].mapmask+1,0 


mov 

byte ptr ES:[BX].mapmask+2,0 


mov 

byte ptr ES:[BX].mapmask+3,1 


mov 

retf 

ES:[BX].Status,lOOh 


/ 

; GENERIC 

/ 

IOCtl (section 6.7.1.9) 


GenericIOCtl: 


cmp 

ES:[BX].Category,8 

/Allow only unit control 

je 

UnitlOCtl 


mov 

retf 

ES:[BX].Status,8103h 

/Unknown Command 

UnitlOCtl: 

cmp 

ES:[BX].Function,44h 

/Write Track 

je 

WriteTrk 


cmp 

ES:[BX].Function, 63h 

/Get Device Parameters 
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je GetParms 

mov ES:[BX].Status,8103h 

retf 

GetParms: 

push es 

les di,ES:[BX].Dbuffer 

mov si,offset bpb 

mov cx,36 

cld 

rep movsb 


pop 

mov 

retf 

WriteTrk: 
mov 
mov 
mov 
push 
push 
push 
Ids 
push 
push 
mov 
mov 
mul 
add 
adc 
mov 
mov 
mov 
mov 
mov 

shiftloop: 
shl 
rcl 
shl 
shr 
jnz 
add 
adc 
mov 
mov 
call 
mov 
pop 


es 

ES:[BX].Status,lOOh 


changeflag,OFFh 

resetflag,1 

bp a sp 

es 

bx 

ds 

si,ES:[BX].Pbuffer 
word ptr ES:[BX].Dbuffer+2 
word ptr ES:[BX].Dbuffer 
ax,[SI].WriteCylinder 
dx,tracksize 
dx 

ax,[SI].WriteFirst 
dx, 0 
bx, ax 
ax, dx 

cx,[SI].WriteCount 
dx,sectorsize/2 
ds,[BP-6] 

bx, 1 
ax, 1 
cx, 1 
dx, 1 

shiftloop 
bx,word ptr phase 
ax,word ptr pbase+2 

dh, 1 
dl,17h 
[DevHlp] 

di, bx 
si 


/Unknown Command 


;save strategy packet 
;es:di - data buffer 
;ds:si - bpb data 
;BPB length + additional bytes 

/Note - driver may block 
/due to reference of 
/unlocked memory 


/set media uncertain 

/media current after RESET MEDIA 

/save address of request packet 


/get parameter buffer 
/Get data buffer address 

/cylinder in ax 

/Sector# of track in DX:AX 
/Starting sector of transfer 

/starting sector in ax:bx 

/Number of sectors 

/restore ds -> main data segment 

/multiply ax:bx by\sector size 

/cx: number of bytes to transfer 


/add physical base address 
/ax:bx = start of track 
/make segment writeable 
/ PhysToUVirt 
/es:di -> RAM address 
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pop 

cld 

ds 

;ds:si -> data buffer 

rep 

movsb 

/perform write 
/Note the strategy routine 
/can suspend here due to 
/reference to unlocked address 

pop 

ds 

/ds->main data segment 

mov 

ax, es 

/release selector from PhysToUVirt 

mov 

dh, 2 


mov 

dl,17h 

/PhysToUVirt 

call 

[DevHlp] 


pop 

bx 

/es:bx-strategy packet 

pop 

es 


mov 

retf 

ES:[BX].Status,lOOh 


/ 

; READ 

/ 

(section 6.7.1.10) 


Read: 

cmp 

changeflag,OFFh 

/Uncertain Media? 

jne 

ReadCertain 

/no, device has been formatted 

mov 

ES:[BX].Status,8110h 

/Uncertain Media Error 

retf 



ReadCertain: 


mov 

• bp,sp 


push 

es 

/save address of request packet 

push 

bx 


mov 

ax,sectorsize 

/Get number of bytes to transfer 

mul 

word ptr ES:[BX].SectorCount 


mov 

cx, ax 


mov 

ax,word ptr ES:[BX].Transfer+2 

/get application buffer address 

mov 

bx,word ptr ES:[BX].Transfer 


mov 

dh, 1 

/make segment writable 

mov 

dl,17h 

/PhysToUVirt 

call 

[DevHlp] 


push 

es 

/save mapped address 

push 

bx 


les 

bx,-4[bp] 

/get request packet address 

mov 

dx,word ptr ES:[BX].SectorNumber 

/get offset of start into ax:dx 

mov 

ax,word ptr ES:[BX].Sectornumber+2 

mov 

cx,sectorsize/2 


ReadShiftLoopl: 


shl 

dx, 1 


rol 

ax, 1 


shr 

cx, 1 


jnz 

ReadShiftLoopl 


mov 

cx,ES:[BX].SectorCount 

/get number of sectors to transfer 

mov 

bx, dx 

/ax:bx = offset to start 
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i 


mov dx,sectorsize/2 

ReadShiftLoop2: 


shl 

cx, 1 


shr 

dx, 1 


jnz 

ReadShiftLoop2 

;cx: number of bytes to transfer 

add 

bx,word ptr phase 

;Now ax:bx = start of transfer 

adc 

ax,word ptr pbase+2 


mov 

dh, 1 

;make segment writeable 

mov 

dl,17h 

;PhysToUVirt 

call 

[DevHlp] 


push 

ds 

;save main data segment 

push 

es 

;save ramdisk selector 

mov 

ax, es 


mov 

ds, ax 

;ds:si = address of RAM sectors 

mov 

si,bx 


les 

di, -8 [BP] 

;Get application buffer address 

cld 



rep 

movsb 

;perform write 

pop 

ax 

/release ramdisk selector 

pop 

ds 


mov 

dh, 2 


mov 

dl,17h 


call 

[DevHlp] 

;PhysToUVirt 

mov 

ax,-6[bp] 

/release application selector 

call 

[DevHlp] 


les 

bx,-4[BP] 

/get strategy address 

mov 

S P, bp 

/restore stack 

mov 

ES:[BX].Status,lOOh 

/Done, success 

retf 



; WRITE 

/ 

(section 6.7.1.11) 


Write: 



cmp 

changeflag,OFFh 

/Uncertain Media? 

jne 

WriteCertain 

/no, device has been formatted 

mov 

ES:[BX].Status,8110h 

/Uncertain Media Error 

retf 



WriteCertain: 


mov 

bp, sp 


push 

es 

/save address of request packet 

push 

bx 


mov 

ax,sectorsize 

/get number of bytes to transfer 

mul 

word ptr ES:[BX].SectorCount 


mov 

cx, ax 


mov 

ax,word ptr ES:[BX].Transfer+2 

/get application buffer address 

mov 

bx,word ptr ES:[BX].Transfer 


mov 

dh, 1 

/make segment writeable 

mov 

dl,17h 

/PhysToUVirt 
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call 

[DevHlp] 


push 

es 

;save mapped address 

push 

bx 


les 

bx,-4[bp] 

;get request packet address 

mov 

dx,word ptr ES:[BX].SectorNumber 

;get offset of start into ax:dx 

mov 

ax,word ptr ES:[BX].SectorNumber+2 

mov 

cx,sectorsize/2 


WriteShiftLoopl: 


shl 

dx, 1 


rol 

ax, 1 


shr 

cx, 1 


jnz 

WriteShiftLoopl 


mov 

cx,ES:[BX].SectorCount 

;get number of sectors to transfer 

mov 

bx, dx 

;ax:bx = offset to start 

mov 

dx,sectorsize/2 


WriteShiftLoop2: 


shl 

cx, 1 


shr 

dx, 1 


jnz 

WriteShiftLoop2 

;cx: number of bytes to transfer 

add 

bx,word ptr phase 

;Now ax:bx = start of transfer 

adc 

ax,word ptr pbase+2 


mov 

dh, 1 

;make segment writable 

mov 

dl,17h 

;PhysToUVirt 

call 

[DevHlp] 


push 

ds 

;save main data segment 

push 

es 

;save ramdisk selector 

mov 

di,bx 

;es:di = address of sectors 

Ids 

cld 

si,-8[BP] 

;Get application buffer address 

rep 

movsb 

/perform write 

pop 

ax 

/release ramdisk selector 

pop 

ds 


mov 

dh, 2 


mov 

dl,17h 


call 

[DevHlp] 

/PhysToUVirt 

mov 

ax,-6[bp] 

/release application selector 

call 

[DevHlp] 


les 

bx,-4[BP] 

/get strategy address 

mov 

sp,bp 

/restore stack 

mov 

retf 

ES:[BX].Status,lOOh 

/Done, success 

codeend: 

maincode 

ends 



end 
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STRAT.ASM 


PAGE ,132 

TITLE OS/2 Driver which records strategy packet contents 

.286 /Enable PUSHA, POPA instructions 

; FILE : STRAT.ASM 
/ 

; Sample Device Driver for OS/2 

; Records strategy packet contents in extra segment 
/ 

; IDC entry: ES:BX has pointer to packet 
; DS has main data segment of device driver 

9 

9 

; devices supported : STRAT$ 

/ 

; command packets are INIT and READ 

; READ copies strategy packet buffer to application buffer 


stdin 

equ 

0 

stdout 

equ 

1 

stderr 

equ 

2 

cr 

equ 

Odh 

If 

equ 

Oah 


Lock 

equ 

13h 

VirtToPhys 

equ 

16h 

PhysToVirt 

equ 

15h 

UnPhysToVirt 

equ 

32h 


Lock 

mov 

ax,UserSelector 

;Selector of driver extra segment 

mov 

bh,type 

;3=permanent lock 

mov 

bl,wait 

;0=no wait in initialize mode 

mov 

dl,Lock 


call 

[DEVHLP] 
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;VirtToPhys 
; Ids 

; mov 

; call 


;PhysToVirt 
; mov 

; mov 

; mov 

; mov 

; mov 

; call 


si,Virtual 
dl,VirtToPhys 
[DEVHLP] 


ax,HighPhys 
bx,LowPhys 
cx,LenPhys 
dh,MapWhere 
dl,PhysToVirt 
[DEVHLP] 


;ds:si = virtual address to convert 
;to physical address 
;Note ds has been changed 
;C clear, AX:BX=physical address 


;AX:BX = physical address 

;CX = length of segment 
;0=ds:si, l=es:di 

;ds must be main data segment 
;at first call to PhysToVirt 


UnPhysToVirt 



mov 

dl,UnPhysToVirt 


call 

[DEVHLP] 

;es not preserved 


maindata segment 'DATA' PUBLIC 
DD -1 
DW 0C080h 
DW StratEntry 
DW IDCEntry 
DB 'STRAT$ ' 

DB 8 DUP (0) 

stratcount DW 0 
stratphys DD 0 
DevHlp DD 0 


;Only one driver 
/Character device driver, IDC 
/Entry point for strategy requests 
/Entry point for inter-device entry 
/Name of driver 
/Reserved, used by OS/2 

/Bytes in stored strategy packet 
/Address of strategy segment 
/Address of device helper routine 


initmsg DB 'STRAT$ is loaded',cr,If 
msglen DW ms glen-initmsg 


dataend label byte 

maindata ends 


extrn DosWrite: FAR 

assume cs:maincode, dsimaindata 
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maincode 

segment 'CODE' PUBLIC 

StratEntry: 

cmp 

byte ptr ES:[BX+2],0 

je 

cmdinit 

cmp 

byte ptr ES:[BX+2],4 

5 e 

cmdread 

mov 

word ptr ES:[BX+14],0 

mov 

word ptr ES:[BX+16],0 

mov 

word ptr ES:[BX+3],8103h 

retf 

/ Initialization (section 6.7.2.1) 

/ 

cmdinit: 

mov 

bp, sp 

push 

bx 

mov 

ax,word ptr ES:[BX+14] 

mov 

word ptr DevHlp,ax 

mov 

ax,word ptr ES:[BX+16] 

mov 

word ptr DevHlp+2,ax 

mov 

ax, seg stratdata 

mov 

bh, 3 

mov 

bl, 1 

mov 

dl,13h 

call 

[DevHlp] 

push 

ds 

mov 

ax,seg stratdata 

mov 

ds, ax 

mov 

si,offset stratdata 

mov 

dl,16h 

mov 

bx,word ptr [BP-2] 

call 

dword ptr ES:[BX+14] 

pop 

ds 

mov 

word ptr stratphys,bx 

mov 

word ptr stratphys+2,ax 

pop 

bx 

mov 

word ptr ES:[BX+14],offset 

mov 

word ptr ES:[BX+16],offset 

mov 

word ptr ES:[BX+3],100h 

mov 

ax,stdout 

push 

ax 

push 

ds 

mov 

ax,OFFSET initmsg 

push 

ax 

push 

msglen 

push 

ds 

mov 

ax,OFFSET msglen 


/command = init? 
/command = read? 

/set length = 0 
/error - bad command 


/save address of DevHlp routine 

/ lock 

/no wait for init routine 
/ Lock 

/save ds 

/convert stratdata to physical address 
/VirtToPhys 


/restore ds 

/save physical address 


codeend 

dataend 
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push ax 

call DosWrite 

retf 


READ (section 6.7.2.2) 


cmdread: 


mov 

bp, sp 


push 

es 

;save address of strategy packet 

push 

bx 


push 

word ptr DevHlp+2 

/make DevHlp addressable 

push 

word ptr DevHlp 


mov 

cx,stratcount 


cmp 

cx,word ptr ES:[BX+18] 

;is character count<atcount? 

ji 

countok 


mov 

cx,word ptr ES:[BX+18] 

/set reduced character count 

countok: 

mov 

word ptr ES:[BX+18],cx 

/set transfer count into packet 

mov 

ax,word ptr ES:[BX+16] 

/destination buffer 

mov 

bx,word ptr ES:[BX+14] 


push 

ax 

/save physical address 

push 

bx 


mov 

stratcount,0 

/res^t strategy dump count 

mov 

dh, 1 

/map into ES:DI 

mov 

dl,15h 

/PhysToVirt 

call 

dword ptr [BP-8] 

'/call DevHlp 

mov 

ax,word ptr stratphys+2 

/strategy dump area 

mov 

bx,word ptr stratphys 


mov 

dh, 0 

/map into DS:SI 

call 

dword ptr [BP-8] 


pop 

bx 


pop 

ax 


jnz 

mapok 


mov 

dh, 1 

/mode change - remap first address 

call 

dword ptr [BP-8] 


mapok: 
cld 

rep movsb 


mov 

dl,32h 

/UnPhysToVirt 

call 

dword ptr [BP-8] 


jnz 

nochange 

/Mode did not change 

sti 


/reenable interrupts 

nochange: 

les 

bx,dword ptr [BP-4] 


mov 

sp,bp 


mov 

word ptr ES:[BX+3],100h 


retf 
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; IDC Entry (section 6 . 1 . 2 . 3 ) 

t 

IDCEntry: 


pusha 


;save all registers 

mov 

bp, sp 


push 

es 

;save strategy packet address 

push 

bx 


xor 

cx, cx 


mov 

cl,byte ptr ES:[BX] 

/length of strategy packet 

mov 

ax,word ptr stratphys+2 

/set ax:bx = strategy store area 

mov 

bx,word ptr stratphys 


add 

bx,word ptr stratcount 

/ax:bx = next store area 

adc 

ax, 0 


add 

stratcount, cx 

/increment statcount 

mov 

dh, 1 

/map into ES:DI 

mov 

dl,15h 

/PhysToVirt 

call 

[DevHlp] 


push 

ds 


Ids 

si,dword ptr [BP-4] 

/ds:si -> strategy packet 

rep 

movsb 


mov 

dl,32h 

/UnPhysToVirt 

pop 

ds 

/restore 

call 

[DevHlp] 


jnz 

coconv 

/No mode change 

sti 


/reenable interrupts 

noconv: 

mov 

es,word ptr [BP-2] 

/restore es 

mov 

sp,bp 


popa 

retf 

codeend: 

maincode 

ends 


stratseg 

segment 'STRAT' PUBLIC 


stratdata 

db 83.92 dup (?) 


stratseg 

ends 



end 
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FORMAT.C 


#include <stdio.h> 

pascal DosOpen(); 
pascal DosClose(); 
pascal DosDevIOCtl(); 
pascal DosExit(); 

unsigned char bytecommand; 

#define MAXSECTOR 1024 
struct { 

unsigned char tracklayout; 
unsigned headnumber; 
unsigned cylindernumber; 
unsigned firstsector; 
unsigned numberofsectors; 
struct { 

int tltsectornum; 
int tltsectorsize; 

} tit[MAXSECTOR]; 

} trackcommand; 

char nulldata = Ob¬ 
struct BPB { 

unsigned sectorsize; 
unsigned char clustersize; 
unsigned reservedsectors; 
unsigned char FATcount; 
unsigned rootentries; 
unsigned totalsectors; 
signed char descriptor; 
unsigned FATsize; 
unsigned tracksize; 
unsigned headcount; 
unsigned hiddensectors; 
unsigned longhiddensectors; 
unsigned long longtotalsectors; 
unsigned char unused[6]; 
unsigned cylindercount; 
unsigned char devicetype; 
unsigned deviceattribute s; 

} bpbdata; 

unsigned char far sectordata[65536]; 

fatset(size,start,index,value) 
int size; 
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unsigned char * start; 
int index; 
int value; 

{ 

int nibbleindex; 
int byteindex; 
int i; 

if (size = 16) 

((int *)start)[index] = value; 

else 

{ 

int temp; 

int * fatword; 

byteindex = (3*index)/2; 

fatword = (int *)(start+byteindex); 

if ((index&l) =0) 

*fatword = (*fatword&0xf000)|(value & Oxfff); 

else 

*fatword = (*fatword&0xF) | ((value&Oxfff)«4); 

} 


main () 

{ 

int errorcode; 
char devicestring[80]; 
char label[80]; 
char yorn[80]; 
unsigned filehandle; 
unsigned action; 
int i,j,reservedsize; 
char * rootptr,* fatptr; 

int rootsize,rootentries,fatlen,size,writesize; 

unsigned maxcluster; 

long devicesize; 

int cylinderno,headno,sectorno; 

int skippedsectors; 

static char FWname[] = "FUTURE "; 

printf("Name of device to be formatted: "); 

scanf("%s",devicestring); 

errorcode = DosOpen(devicestring,&filehandle,fiaction,0L,0,1,0x8012,0L); 
if (errorcode) 

{ 

printf("error in device open %d\n",errorcode); 
exit(errorcode); 

} 

printf("Enter 11-character volume label: "); 
s canf("%s",label); 

printf("Skip format step (Y/N)? "); 
scanf("%s",yorn); 
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streat(label," "); 

bytecommand = 0; 

errorcode = DosDevIOCtl(&nulldata,&bytecommand,0,8,filehandle); 
if (errorcode) 

{ 

printf("error in Lock Drive %d\n",errorcode); 
exit(errorcode); 

} 

errorcode = DosDevIOCtl(&bpbdata,&bytecommand,0x63,8,filehandle); 
if (errorcode) 

{ 

printf("error in Get Device Parameters %d\n",errorcode); 
exit(errorcode); 

} 

for (i=0;KMAXSECTOR;i++) 

{ 

trackcommand.tit[i].tltsectornum = i+1; 

trackcommand.tit[i].tltsectorsize = bpbdata.sectorsize; 

} 

for (i=0;i<bpbdata.sectorsize*bpbdata.tracksize;i++) 
sectordata[i] = 0; 
if (yorn[0] == 'n' || yorn[0]~'N') 

for (i=0;i<bpbdata.cylindercount;i++) 
for (j=0;j<bpbdata.headcount;j++) 

{ 

trackcommand.tracklayout=l; 
trackcommand.headnumber = j; 
trackcommand.cylindernumber = i; 
trackcommand.firstsector = 0; 

trackcommand.numberofsectors = bpbdata.tracksize; 
errorcode = 

DosDevIOCtl(sectordata,fitrackcommand,0x44,8,filehandle) 
if (errorcode) 

{ 

printf("Error formatting track %d\n",errorcode); 
exit(errorcode); 

} 

printf("Head %d Cylinder %d \n",j,i); 

} 

reservedsize = bpbdata.sectorsize*bpbdata.reservedsectors; 
for (i=0;i<reservedsize;i++) 
sectordata[i] = 0; 
for (i=0;i<sizeof(struct BPB);i++) 

sectordata[i+11] = ((char *)(fibpbdata))[i]; 
strnepy(sectordata+3,FWname,8); 
fatptr = sectordata + reservedsize; 
fatlen = bpbdata.FATsize * bpbdata.sectorsize; 
for (i=0;i<bpbdata.FATcount*fatlen;i++) 
fatptr[i] = -1; 

rootptr = fatptr + bpbdata.FATcount * fatlen; 
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rootsize = bpbdata.sectors!ze * 

((bpbdata.sectorsize -1 + 32*bpbdata.rootentries)/ 

bpbdata.sectorsize); 

rootentries = rootsize / 32; 

writesize = reservedsize + fatlen*bpbdata.FATcount + rootsize; 
skippedsectors = writesize / bpbdata.sectorsize; 
if (bpbdata.totalsectors != 0) 

{ 

devicesize = bpbdata.totalsectors * bpbdata.sectorsize; 

maxcluster = (bpbdata.totalsectors-skippedsectors) / bpbdata.cluster- 

size+2; 

if (bpbdata.totalsectors <= 20740) 
size = 12; 

else 

size = 16; 

} 

else 

{ 

devicesize = bpbdata.longtotalsectors * bpbdata.sectorsize; 
maxcluster = 

(bpbdata.longtotalsectors-skippedsectors) / bpbdata.clustersize+2; 
if (bpbdata.totallongsectors <= 20740) 
size = 12; 

else 

size = 16; 

} 

for (i=2;iCmaxcluster;i++) 

for (j=0;j<bpbdata.FATcount;j++) 

fatset(size,fatptr+j*fatlen,i, 0); 
for(i=0;i<bpbdata.FATcount;i++) 

{ 

fatset(size,fatptr+i*fatlen,0,bpbdata.descriptor); 
fatset(size,£atptr+i*fatlen,1,-1); 

} 

for (i=0;i<rootentries;i++) 
for (j=0;j<32;j++) 

rootptr[i*32+j] = 0; 
for (i=0;i<ll;i++) 

rootptr[i] = label[i]; 
rootptr[11] = 8; 
for (i=0;i<skippedsectors;i++) 

{ 

cylinderno = 

i / (bpbdata.tracksize * bpbdata.headcount); 
headno = 

(i - cylinderno*bpbdata.tracksize*bpbdata.headcount)/ 

bpbdata.tracksize; 

sectorno = 

(i - cylinderno*bpbdata.tracksize*bpbdata.headcount 

- headno*bpbdata.tracksize); 
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trackcommand.tracklayout = 1/ 
trackcommand.headnumber = headno; 
trackcommand.cylindernumber = cylinderno; 
trackcommand.firstsector = sectorno; 
trackcommand.numberofsectors = 1; 
errorcode = 

DosDevIOCtl(sectordata+i*bpbdata.sectorsize, 
fitrackconunand, 0x44, 8, filehandle) ; 
if (errorcode) 

{ 

printf ("Error in writing sector %d\n"., errorcode) ; 
exit(errorcode); 

} 

} 

DosClose(filehandle); 

DosExit(0,0); 

} 
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DMPSTRAT.C 


#include <stdio.h> 

pascal DosOpen(), DosRead(), DosClose(), DosExit(); 

#define MAXCOUNT 8192 
#define MAXLINE 16 

unsigned static char stratbuffer[MAXCOUNT]; 
unsigned count; 

hexprint(buffer,count) 
char * buffer; 
int count; 

{ 

int i; 

for(i=0;i<count;i++) 

{ 

static char hexchar [17] = "0123456789ABCDEF"; 

printf("%c%c ",hexchar[(buffer[i]&0xF0)>4],hexchar[buffer[i]&0xF]); 
if (i%MAXLINE==MAXLINE-l | | i=count-l) 
printf("\n"); 

} 

} 

main() 

{ 

int filehandle; 
int i, j; 
int packetlen; 
int action; 
int errorcode; 

errorcode = DosOpen((char far *)"STRAT$",(char far *)&filehandle, 

(char far *)fiaction,OL,0,1,0x0040,0L); 
errorcode = DosRead(filehandle,(char far *)stratbuffer,MAXCOUNT, 

(char far *)ficount); 
i=0; j=0; 
while (Kcount) 

{ 

j++; 

packetlen = (int)(stratbuffer[i]); 
printf("Strategy packet #%d:\n", j); 
hexprint(stratbuffer+i,packetlen); 
printf("\n"); 
i+=packetlen; 

} 

errorcode = DosClose(filehandle); 
errorcode = DosExit(0,0); 

} 
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RAMDRV.DEF 


LIBRARY 


DMPSTRAT.DEF 


NAME dmpstrat WINDOWCOMPAT 


STRAT.DEF 


LIBRARY 

SEGMENTS 

maindata CLASS ' DATA' 
maincode CLASS 'CODE' 
stratseg CLASS 'STRAT' IOPL 
PROTONLY 


RAMDRV.CMD 


cl /c /AL format 
link format,,,, format 
cl /c /AL dmpstrat,, ,,dmpstrat 
link dmpstrat,,,,dmpstrat 
masm strat; 

link strat,strat.sys,,os2,strat 
masm ramdrv; 

link ramdrv, ramdrv. sys,, os2, ramdrv 
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A 

Addressing 

segmented scheme, 8-10 
virtual addressing, 10 
AllocGDTSelector, 36, 63 

in initialization time, 211-212 
AllocPhys, 36, 63 

in initialization time, 209-210 
in strategy time, 235-236 
AllocReqPacket, 40 

in strategy time, 255-256 
API calls, 12,17, 33 

in initialization time, 61-62 
Application program support, block 
device drivers, 71, 75 
AttachDD helper service, 66, 90 
Attribute fields, fisting of, 27 

B 

Bi-modal operations, 60 
device driver, 21-22 
helper routines, at strategy time, 86- 
87 

tile selectors, 21 

BIOS parameter block format 12 76 
extended form, 430-431 
short form, 429-430 
Bit flags 

device attribute word bit flags, 146 
device types, 142 
Block I/O, 12 
Block, 34-35 

in strategy time, 228-230 
Block device drivers 

application program, 76-77 
file manager support, 74, 75-76 
format program support, 74-75 
high-level format, 71 
layout of partitioned drive, 72 
removable media support, 71, 75 
request packets, 31-34 
strategy packets 

BUILD BPB, 112-114 


CLOSE, 117 

MEDIA CHECK, 109-111 
OPEN, 115-116 
READ, 118-119 

REMOVABLE MEDIA, 114-115 
RESET MEDIA, 108-109 
WRITE, 119-120 
WRITE/VERIFY, 121-126 
Block device IOCtl packets 

Block Removable IOCtl, 135-136, 381 
Category 8 IOCtl packets, 130-131 
Category 9 IOCtl packets, 131-132 
Format and Verify Track IOCtl, 156- 
160 

Get Device Parameters, 138-142,163- 
165 

Lock Drive, 132-133 
Lock Physical Drive, 160-161 
Physical Read Track, 168-172 
Physical Verify Track, 172-175 
Read Track IOCtl, 150-153 
Redetermine Media IOCtl, 136-138 
Set Device Parameters, 142-146 
Unlock Drive, 133-135 
Unlock Physical Drive, 162 
Verify Track IOCtl, 153-156 
Write Track IOCtl, 146-150 
Block devices, 67, 68-77 

disk partitioning software, 71, 73-74 
format of physical drive, 68 
I/O requests, flow of, 70 
logical unit control, 71, 74 
low-level format, 71, 72-73 
physical disk control, 69, 72 
sector number sequence, 69 
unit number, request packets, 29 
Boot sectors, 12 
format, 427-428 
BUILD BPB 

extended format, 139, 140-141, 144- 
145 

features of, 112-114 
format, 376 
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removable devices, 138,142 
request, 31 
BUSY bit, 32, 82 

C 

CLI, interrupt protection, 49, 50 
Category 8 IOCtl packets, 130-131 See 
also Block device IOCtl packets 
listing of, 384-396 
Category 9 IOCtl packets, 131-132 
Category byte, 32 
Chaining, 14 

"Call interrupted" error, 33 
Character device drivers, 67, 77-82, 97 
deinstallation, 77 
devic status, 82 
reques packets, 30-31 
strategy packets 
CLOSE, 177-178 
INPUT FLUSH packet, 183-184 
INPUT STATUS, 182 
Monitor CLOSE packet, 186-187 
Monitor OPEN packet, 185-186 
NONDESTRUCTIVE READ NO 
WAIT, 181 
OPEN, 175-177 

OUTPUT FLUSH packet, 184-185 
OUTPUT STATUS, 182-183 
READ, 178-179 
WRITE, 179-180 
Character device IOCtl packets 
Flush Input Buffer packet, 192-193 
Flush Output Buffer packet, 194-195 
Query Monitor Support packet, 187- 
189 

Register a Monitor packet, 189-192 
Character file I/O, 12-13, 78-79 
Device CLOSE, 78 
Device OPEN, 78 

NONDESTRUCTIVE READ NO 
WAIT, 79 

READ request, 78-79 
WRITE request, 79 


Character monitor, 55-59, 79-82 
creation in initialization time, 64 
interrupt service routine with monitor 
support, 56, 58 
monitor chain 
creation of, 55 
dispatch character, 57-58 
flushing, 59 
monitor thread 
deregister, 59 
register, 55, 57 
notification routine, 58-59 
Character monitor management, 39-40 
DeRegister, 40 59 
in strategy time, 269 
helper routines, 39-40 
MonFlush, 40 
MonitorCreate, 39 

in initialization time, 223-224 
in strategy time, 264-267 
MonWrite, 40 

in interrupt time, 300-301 
in strategy time, 270-271 
Register, 39-40 

in strategy time, 267-268 
Character queues, 82 
format, 365 
CHR bit, 26 
CHR flag, 26 
Clear Interrupt Flag, 5 
CLK flag, 25 
Clock tick, 54-55, 96-97 
CLOSE 

features of, 117,177-178 
format, 378 

Command code, request packets, 29 
Compatibility box 
drivers, 26 
interrupts, 15 
3.x, 10 

COM ports, 16 66 
CONFIG.SYS, 44, 45 
Cylinders, block device, 68 
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D 

DEINSTALL packet, 30, 46, 77-78 
features of, 107-108 
format, 380 
DeRegister, 40 

in strategy time, 269 
DevDone, 35 

in interrupt time, 281-282 
in strategy time, 231-232 
Device Attribute Word (DAW), 25 
format, 364-365 
Device CLOSE, 78 
Device controller, 2-4 

Direct Memory Access (DMA) data 
transfer, 4 

I/O port addressing, 2 
memory-mapped address, 4 
Device drivers 

I/O commands, 46-51 
attribute fields, listing of, 27 
bi-modal support, 21-22 
block devices, 68-77 
character devices, 77-82 
character monitor, 55-59 
clock tick, 54-55, 96-97, 
components, 17 
device header, 25, 28 
driver communication time, 97-98 
entry points, 18-19 
as event-driven program, 43 
function of, 1, 43 
hardware interrupt, 51-54 
headers, 44-45 

helper routines, 20-21, 34-42, 83-91 
initialization, 17, 60-66 
installation, 44-46 
interrupt time, 91-96 
IOCtl interfaces, 83 
notification time, 96 
request packets, 28-34 
segment structure, 23-28 
main data segment, 25-28 
memory layout, 23-24 


strategy routines, 17, 66-68 
as teaching tool, 2 

Device driver header attribute word, 71 
Device Driver Standard Error Codes, 
listing of, 372 

Device driver structures, 363-36 
character queue format, 365 
Device Attribute Word (DAW) format, 
364-365 

driver header format, 363-364 
global INFO segment format, 366-367 
local INFO segment format, 368 
monitor word format, 366 
Device OPEN, 78 

Direct Memory Access (DMA) data 
transfer, device controller, 4 
Directory entry, formats, 432-433 
DosMonClose, 59, 79, 81 
DosMonOpen, 55, 79, 81, 88 
DosMonReg, 55, 80, 88 
DosMonReg API call, 33 
DOS variables, accessing 

in initialization time, 65, 225-226 
in interrupt time, 302-303 
in strategy time, 272-274 
Drivers 

communication time, 97-98 
in initialization time, 66 
at strategy time, 90-91 
DWORD area, 89 

E 

Edge-sensitive machines, 52 
Edge-triggering, 6 
End of Interrupt, 6 
Entry points 

device driver, 18-19 
inter-device communication entry 
points, 19, 28 
interrupt entry points, 18 
notification entry points, 18,19 
timer entry points, 18 
EOI, 37 
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in initialization time, 207-208 
in interrupt time, 304 
Errors, system-defined errors, 103-104 

F 

FAR CALL, 45, 47, 52, 54 
FAR JUMP instruction, 15,16 
FAR RETURN instruction, 15,16,45 48, 
64 

FDISK, 32 

File Allocation Table (FAT), 12, 431-432 
entries, 432 

File management, OS/2,12-13 
File manager 
strategy packets 

GET FIXED DISK/LOGICAL 
UNIT MAP, 127-129 
PARTITIONABLE FIXED DISKS, 
127 

support, block device drivers, 74-76 
Final buffer, 55, 64 
FLUSH, format, 378 
Flush Input Buffer, 33 
feature of, 192-193 
format, 390 

FLUSH INPUT QUEUE, 82 
Flush Output Buffer, 33 
feature of, 194-195 
format, 391 

FLUSH OUTPUT QUEUE, 82 
Format and Verify Track IOCtl, features 
of, 156-160 

FORMAT program, 32 

support, block device drivers, 74-75 
Format Track 
format, 385 

format track table, 159-160 
FreePhys, 36 

in initialization time, 210-211 
in strategy time, 236-237 
FreeReqPacket, 40 

in strategy time, 256-257 
FSRAM semaphores, 87 
Function byte, 32 


G 

Generic I/O control, 12,13, 67 

Generic IOCtl packets, 101 
error codes, 197 
format of, 197-199 
listing of, 379 
vs. strategy packets, 100 
system-defined IOCtls, 195-196 
user-defined IOCtls, 196 

Get Device Parameters 

device types defined for, 141 
features of, 138-142,163-165 
format, 382 

GetDOSVar, 41-42, 55, 57, 91, 95 
in initialization time, 225-226 
in interrupt time, 302-303 
in strategy time, 272-274 

GET FIXED DISK/LOGICAL UNIT 
MAP 

features of, 127-129 
format, 381 

Get Physical Device Parameters, format, 
389 

GIO bit, 26 

Global Descriptor Table, 8, 44, 84 

Global INFO segment, 91 
format, 366-367 

H 

Hardware 

device control, 2-4 
interrupt hardware, 4-7 
process management hardware, 8-10 
real mode, 10-11 

Hardware interrupt, 51-54, 63 
interrupt manager, 52-54 

Headers 

driver device header, 25, 28, 44-45 
format, 363-364 

information in main data segment, 
25-28 

strategy packets, 28-29 
features of, 102-104 
format, 369-370 
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Heads, block device, 68 
Helper routines, 20-21, 34-42 See also 
specific routines 

initialize time helper routines, 202- 
227 

interrupt time helper routines, 20, 
279-305 

memory management, 20 
monitor management, 21 
process management, 20 
queue management, 20 
semaphore management, 20 
strategy time helper routines, 83-91 
228-279 

summary of, 397-42 
system services, 21 
timer management, 20 
High-level format, block device drivers, 
71 

I 

I/O commands, 46-51 

interrupt-driven drivers, 50, 51 
I/O requests and, 46-47 
polled device drivers, 50 
strategy routine and, 47-48, 51 
I/O modes 
block I/O, 12 
character I/O, 12-13 
Generic I/O control, 12,13 
I/O port addressing, device controller, 
2 

IBM bit, 26 
IDC bit, 25 

IDC data structure, format, 227 
IDC interface, at interrupt time, 95 
Implementation strategies. See also 
specific techniques and examples 
examples 

PIPER, 321-340 
RAMDRV, 340-345 
TIMDMP, 345-356 
nested interrupt technique, 315, 321 


single interrupt technique, 312, 315 
strategy only technique, 307, 310 
INFO segment, 16, 65 
Global, 91, 366-367 
Local, 91, 368 
Initialization, 60-66 
API calls, 61-62 
deinstallation and, 60 
device driver, 17 
routines, 60-61 
strategy packets 

DEINSTALL packet, 30, 99-100 
INIT packet, 30, 99-100 
Initialization time helper routines, 202- 
227 

character monitor management, cre¬ 
ate monitor chain, 64, 223-224 
communication between device 
drivers, 66, 226-227 
interrupt management, 62-63 
clear IRQ level of PIC, 207-208 
intercept hardware interrupt, 205- 
207 

remove interrupt handler, 208-209 
stack requirements, alert system, 
203-204 

memory management, 63-64 

allocate and map local sector, 214- 
215 

allocating global sectors, 211-212 
allocating memory, 209-210 
deallocating memory, 210-211 
lock device driver segments, 219- 
220 

mapping memory to global sectors, 
212-213 

release local sector, 215 
temporary-mode-independent 
map, 216-218 

terminate-mode-independent map, 
218-219 

system services, return pointer to 
DOS variable 65, 225-226 
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timer management 64 

register-n-tick timer handler, 221- 
222 

register single-tick timer handler, 
220-221 

remove timer handler, 222-223 
INIT packet, 30 
features of, 105-107 
format, 374-375 
INPUT, format, 378 
INPUT FLUSH packet, 31, 33 
features of, 183-184 
INPUT STATUS packet, 82 
feature of, 182 
request, 30 
Installation, 44-46 

initialization thread, action of, 44-46 
Inter-device communication 
driver communication, 66 
entry points, 19 28 
Interrupt Descriptor Table, 9 
Interrupt-driven drivers, I/O commands, 
50, 51 

Interrupt hardware 
interrupt flags, 5 
interrupt service routine, 5 
Programmable Interrupt Controller 
(PIC), 5-7 

Interrupt management, 2 See also In¬ 
terrupt time helper routines 
EOI, 37 

in initialization time, 62-63, 207- 
208 

in interrupt time, 94, 304 
Register Stack Usage, in initialization 
time, 203-204 
SetIRQ, 37 

in initialization time, 205-207 
in interrupt time, 276-278 
at strategy time, 87 
UnSetIRQ, 37 

in initialization time, 208-209 
in interrupt time, 305 
in strategy time, 279 


Interrupt Request Number, 5 
Interrupts 3 
chaining, 14 
compatibility box, 15 
definition, 4 
entry points, 18 
event related to, 4-7 
hardware interrupt, 52-54 
ID interface, 95 
interrupt manager, 4-5 
interrupt service routine, 5 
nested interrupts, 8 
OS/2 handling of, 15 
Interrupt time helper routines, 37, 91- 
96, 279-305 

character monitor management, 95 
write monitor character packet to 
monitor chain, 300-301 
communicating between device 
drivers, 303 

interrupt management, 94 

clear interrupt level of interrupt 
controller, 304 

remove hardware interrupt hand¬ 
ler, 305 

memory management, 93-94 
map to global sector, 284-285 
temporary mode-independent map, 
285-286 

terminate mode-independent map, 
288 

process management 92 

flag I/O completion in kernel, 281- 
282 

resume previously blocked strategy 
routine, 280-281 

return to real mode from protect 
mode, 283 

switch from real mode to protect 
mode, 282 

queue management 95 

flush character queue, 295-296 
get next request packet from 
queue, 292-293 
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initialize character queue, 294 
insert character in queue, 296 
remove specified packet from 
queue, 293 

return character from queue, 297 
semaphore management, 94 
get handle for, 289-290 
release a semaphore, 291-292 
release handle for, 290-291 
system services, return pointer to 
DOS variable, 95-96, 302 
timer management, 94 

call timer handler each n-tick, 297- 
299 

remove timer handler, 299 
IOCtl category codes, system defined, 33 
IOCtl calls, 32 83 
IOCtl interface, 67-68 83 
IOCtl strategy packet, 32 83 
IRQ levels, preassigned, 276 

K 

KBD flag, 25 

L 

Length byte, request packets, 29 
Level-sensitivity, Programmable Inter¬ 
rupt Controller, 7 
Local Descriptor Table, 8, 84 
Local INFO segment, 91 
format, 368 
Local semaphores, 13 
Lock, 37 

in initialization time, 219-220 
in strategy time, 245-246 
Lock Drive 

features of, 132-133 
format, 380 
Lock Physical Drive 
features of, 160-161 
format, 386 

Logical unit control, block devices, 71,74 
Logical unit maps, 128 
Logical unit numbers, 128 


Low-level format, block devices, 71, 72- 
73 

M 

Machine status word, 10, 84 
MEDIA CHECK packet, 32 75-76 
features of, 109-111 
format, 375-376 

Memory layout, device driver, 23-24 
Memory management, 20, 36-37 
AllocGDTSelector, 36 

in initialization time, 211-212 
AllocPhys, 36 

in initialization time, 209-210 
in strategy time, 235-236 
FreePhys, 36 

in initialization time, 210-211 
in strategy time, 235-236 
helper routines, 36-37 

in initialization time, 63-64 
at interrupt time, 93-94 
Lock, 37 

in initialization time, 219-220 
in strategy time, 245-246 
PhysToUVirt, 36-37 

in initialization time, 212-214 
in interrupt time, 284-285 
in strategy time, 237-238 
PhysToVirt 

in initialization time, 216-218 
in interrupt time, 285-287 
in strategy time, 240-243 
Memory management 
at strategy time, 84-87 
bi-modal operations, 86-87 
protect mode, 84-85 
real mode, 85-86 
Unlock, 37 

in strategy time, 247 
UnPhysToVirt 

in initialization time, 218-219 
in interrupt time, 288 
in strategy time, 243 
Verify Access, 37 
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VirtToPhys, 37 

in strategy time, 246-247 
Memory-mapped address, device 
controller, 4 
MonFlush, 40, 59 

in strategy time, 271-272 
Monitor chain, 33, 64, 80 
creation of, 55 
dispatch character, 57-58 
flushing, 59 
uses by driver, 80 
Monitor CLOSE packet, 31 
features of, 186-187 
MonitorCreate, 39.59 

in initialization time, 223-224 
in strategy time, 264-267 
Monitor dispatcher, 13, 64, 80-81 
Monitoring, 77, 79 

Monitor management, 2 See also Char¬ 
acter monitor management 
at interrupt time, 95 
at strategy time, 88-89 
Monitor OPEN packet, 31 
features of, 185-186 
"Monitors not supported" error, 33 
Monitor support, 33 
Monitor thread 13, 80 
deregister, 59 
register, 55, 57 
Monitor word, format, 366 
MonWrite, 40, 58, 80, 81, 88 
in interrupt time, 300-301 
in strategy time, 270-271 
MonWrite DevHlp, 96 

N 

Nested interrupt technique, 8, 315, 321 
algorithm, 315, 321 

NONDESTRUCTIVE READ NO WAIT 
packet, 31, 79 
features of, 181 
format, 377 

Notification entry points, 18,19 
Notification routine, 13, 64, 81 


character monitor, 58-59 
Notification time, 96 
NULL flag, 25 

O 

OPEN 

features of, 115-116,175-177 
format, 378 
OPN bit, 26 
OS/2 

compatibility box, 14-15 
DOS variables, 16 
file management, 12-13 
interrupt handling, 15 
memory management, 13 
process management, 11 
semaphores, 13-14 
thread management, 11 
timer handling, 15-16 
OUTPUT packet, format, 378 
OUTPUT FLUSH packet, 31, 34 
features of, 184-185 
OUTPUT STATUS packet, 30, 82 
features of, 182-183 

P 

PARTITIONABLE FIXED DISK packet 
features of, 127 
format, 380 
Partitioning disk, 32 
software, 71, 73-74 

Partition description entry format, 424- 
424, 428-429 

Partition table, format, 428 
Physical disk control, block devices, 69, 
72 

Physical file format, summary of, 427- 
433 

Physical Read Track 
features of, 168-172 
format, 388 

Physical Verify Track, features of, 172- 
175 

Physical Write Track, format, 387 
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PhysToGDTSelector, 63 
PhysToUVirt, 36-37, 63, 85 
in initialization time, 212-214 
in interrupt time, 284-285 
in strategy time, 237-238 
PhysToVirt, 63, 86 

in initialization time, 216-218 
in interrupt time, 285-287 
in strategy time, 240-243 
PIPER, 321-340 

compile and run, 340 
driver, 309 
PIPE IN$ 

close logic, 327 
flowcharts, 323-324 326 
initialization, 321-322 
open logic, 322 
read logic, 327 
write logic, 322, 325 
PIPE OUT$ 

close logic, 336, 340 
flowcharts, 328-331, 333-335, 337- 
339 

initialization, 327 
open logic, 332 
read logic, 332, 336 
write logic, 336 
program summary, 435-46 
Polled operation, 3 
I/O commands, 50 
Process, OS/2 management, 11 
Process management, 20, 34-35 
Block, 34-35 

in strategy time, 228-230 
DevDone, 35 

in interrupt time, 92, 281-282 
in strategy time, 231-232 
helper routines, 34-35 
ProtToReal, 35-36 
in interrupt time, 283 
in strategy time, 234 
RealTbProt, 35-36 
in interrupt time, 282 
in strategy time, 233 


Run, 35 

in initialize time, 230-231 
in interrupt time, 280-281 
at strategy time, 83-84 
TC Yield, in strategy time, 232 
Process Status Word, 5 
Programmable Interrupt Controller 
(PIC), 5-7 

Protect mode, 10, 26 
drivers, 44 

helper routines, at strategy time, 84- 
85 

indicator flag 16 
at strategy time, 84-85 
ProtToReal, 35-36 
in interrupt time, 283 
in strategy time, 234 
PullParticular, 41 
in interrupt time, 293 
in strategy time, 254-255 
PullReqPacket, 41 

in interrupt time, 292-293 
in strategy time, 253-254 
PushReqPacket, 41 
in strategy time, 253 

Q 

Query Monitor Support, 31 
feature of 187-189 
format, 391 

Queue linkage word, request packets, 29 
Queue management, 20, 40-41 
allocate strategy packet, 255-256 
AllocReqPacket, 40 

in strategy time, 255-256 
flush character queue, 259 
FreeReqPacket, 40 

in strategy time, 256-257 
free strategy packet, 256-257 
get handle for, 248-249 
get next request packet, 253-254 
helper routines, 40-41 
initialize character queue, 258 
insert character in queue, 259-260 
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at interrupt time, 95 
place request packet, 253 
PullParticular, 41 

in interrupt time, 293 
in strategy time, 254-255 
PullReqPacket, 41 

in interrupt time, 292-293 
in strategy time, 253-254 
PushReqPacket, 41 
in strategy time, 253 
QueueFlush, 41 

in interrupt time, 295 
in strategy time, 259 
Queuelnit, 41 

in interrupt time, 294 
in strategy time, 258 
QueueRead, 41 

in interrupt time, 297 
in strategy time, 260 
QueueWrite, 41 

in interrupt time, 296 
in strategy time, 259-260 
release handle for, 249 
release semaphore, 251-252 
remove specific packet, 254-255 
request semaphore, 250-251 
return character from queue, 260 
semaphore management, 87 
SortReqPacket, 41 

in strategy time, 89-90, 257 
sort request packet, 257 

R 

RAMDRV, 345-356 

compile and run, 359, 362 
program summary, 477-50 
RAMDRV driver, 310, 345 

flowcharts, 347-348, 350-352, 354- 
355 

initialization, 346 
strategy entry, 346 
strategy routines, 349, 353, 356 
STRAT 

flowcharts, 357-358, 360-361 


IDC entry, 359 
initialization, 356 
read, 359 

RAM semaphores, 14, 87 
READ, 31, 59, 78-79 

features of, 118-119,178-179 
format, 377 
Read Track 

features of, 150-153 
format, 384 
Real mode, 14,17 
drivers, 44 

helper routines, at strategy time, 85- 
86 

at strategy time, 85-86 
RealToProt, 35-36 
in interrupt time, 282 
in strategy time, 233 
Redetermine Media 
features of, 136-138 
format, 381 
Register, 39-40 

in strategy time, 267-268 
Register a Monitor, 31 
features of, 189-192 
format, 389 

RegisterStackUsage, 63 

in initialization time, 203-204 
REINSTALL packets, format, 376 
REMOVABLE MEDIA 32, 75 
features of, 114-115 
format, 379 

Removable media support, block device 
drivers, 71, 75 
Request packets, 28-34 

block device unit number, 29 
command code, 29 
length byte, 29 
queue linkage word, 29 
status request packets, 47-48 
status word, 29 
RESET MEDIA, 32, 76 
features of, 108-109 
format, 380 
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ResetTimer 

in initialization time, 222-223 
in interrupt time, 299 
in strategy time, 263-264 
Return from Interrupt instruction, 5,15 
Ring privilege, 9 
ROM BIOS routine, 15 
Run, 35 

in initialize time, 230-231 
in interrupt time, 280-281 

S 

Scheduler queue, 47 
SCR flag, 25 
Sectors, size codes, 159 
Segment registers, 10 
SEGMENTS command, 46 
Segment structure, 23-28 
main data segment, 25-28 
memory layout, 23-24 
Selector registers, 9,10 
Semaphore management, 20, 38 
helper routines, 38 
at interrupt time, 94 
SemClear, 38 

in interrupt time, 291 
in strategy time, 251-252 
SemHandle, 38 

in interrupt time, 289-291 
in strategy time, 87, 248-250 
SemRequest, 38 

in strategy time, 250-251 
Semaphores 
local semaphores, 13 
RAM semaphores, 14, 38 
system semaphores, 13 
Set Device Parameters 

device types defined for, 146 
features of, 142-146 
format, 383 
Set Interrupt Flag, 5 
SetIRQ, 37, 63 

in initialization time, 205-207 


in interrupt time, 276-278 
SetTimer, 39, 64 

in initialization time, 220-221 
in strategy time, 261-262 
SHR bit, 26 

Single interrupt technique, 312, 315 
algorithm, 312, 315 
Single-mode drivers, 44 
SortReqPacket, 41 
in strategy time, 257 
Special-device flags, 25-26 
Stack requirements, calculation of, 63 
Standard load library module, 23 
STATU word, 29 
format, 370-371 
STI, interrupt protection, 49 
Strategy only technique, 307, 310 
algorithm, 310, 312 
Strategy packets, 66 

block device drivers, 100-101, 1 OS- 
126 

block device IOCtl packets, 129-175 
block device request packets, 31-34 
character device drivers, 101,175-187 
character device IOCtl packets, 187- 
195 

character device request packets, 30- 
31 

DEINSTALL packet, 30, 99-100 
features of, 107-108 
file manager, 126-129 
Generic IOCtl packets, 195-199 
header, 28-29 

features of, 102-104 
format, 369-370 
INIT packet, 30, 99-100 
features of, 105-107 
vs. IOCtl packets, 100 
listing of, 373-374 

Strategy routine, 17, 25, 66-68, 363-36 
and I/O, 47-48, 51 
registers at entry to, 67 
scheduling/rescheduling, 47 
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Strategy timer helper routines, 83-91, 
228-279 

character monitor management, 88- 
89 

create monitor chain, 264-265 
delete monitor chain, 266-267 
deregister monitor from monitor 
chain, 269 

flush monitor chain, 271-272 
register monitor to monitor chain, 
267-268 

write monitor packet character to 
monitor chain, 270-271 
communicating between device 
drivers, 90-91, 274-276 
interrupt management, 87 

intercept hardware interrupt, 276- 
278 

remove hardware interrupt hand¬ 
ler, 279 

memory management, 84-87 See also 
allocate physical memory, 235-236 
convert virtual address to physical 
address, 246-247 

lock virtual memory against swap 
or relocation, 245-246 
map physical memory to process- 
local selector, 238-239 
map to global sector, 237-238 
release physical memory, 236-237 
temporary mode-independent map, 
240-243 

terminate mode-independent map, 
243 

terminate process-local map, 240 
unlock virtual memory, 247 
verify virtual memory addres¬ 
sability in process context, 244 
process management, 83-84 
block strategy routine, 228-230 
flag I/O completion in kernel, 231- 
232 

resume previously blocked strategy 
routine, 230-231 


return to real mode from protect 
mode, 234 

switch from real mode to protect 
mode, 233 

yield to priority threads, 232 
yield to time-critical threads, 232 
system services, return pointer to 
DOS variable, 272-274 
timer management, 87-88 

register an n-tick, handler, 262-263 
register new entry point called at 
each tick, 261 

remove timer handler, 263-264 
System-defined driver independent 
functions, 33 

System-defined IOCtl packets, 383-39 
generic type, 195-196 
System semaphores, 13, 87 
System services,>21, 41-42 
GetDOSVar, 41-42 

in initialization time, 225-226 
in interrupt time, 302-303 
in strategy time, 272-274 
helper routines, 41-42 
at interrupt time, 95-96 
at strategy time, 91 

T 

TCYield, 91 

in strategy time, 232 
Terminate-and-stay-resident program, 
77 

Thread 

components, 8 
memory addressing, 9 
monitor threads, 13 
OS/2 management, 11 
Tick Count, 39, 64 

in initialization time, 221-222 
in interrupt time, 297-299 
in strategy time, 262-263 
Tiled selectors 21 60 
TIMDMP, 340-345 

compile and run, 343, 345 
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driver, 309 
flowcharts, 342 344 
initialization, 340-341 
IOCtl strategy routine, 341 
program summary, 463-47 
timer handler, 343 
Time-out period, 47 
Timer 

OS/2 handling of, 15-16 
timer entry point, 16,18 
Timer management, 20, 38-39 
helper routines, 38-39 
in initialization time, 64 
at interrupt time, 94 
ResetTimer 

in initialization time, 222-223 
in interrupt time, 299 
in strategy time, 263-264 
SetTimer, 39 

in initialization time, 220-221 
in strategy time, 261-262 
Tick Count, 39 

in initialization time, 221-222 
in interrupt time, 297-299 
in strategy time, 262-263 
Tracks 

block device, 68 

track layout table, 148,149,152,156, 
168,171,174 
Transmitter driver, 98 

U 

"Uncertain media" error, 32, 71 
Unlock, 37 

in strategy time, 247 
Unlock Drive 

features of, 133-135 
format, 381 


Unlock Physical Drive 
features of, 162 
format, 386 
UnPhysToVirt 

in initialization time, 218-219 
in interrupt time, 288 
in strategy time, 243 
UnSetIRQ, 37 

in initialization time, 208-209 
in interrupt time, 305 
in strategy time, 279 
User-defined IOCtls, generic type, 196 

V 

Variables, codes, listing of, 225, 273 
Verify Access, 37 
Verif Track , 

features of, 153-156 
format, 385, 388 
VirtToPhys, 37 

in strategy time, 246-247 
Virtual addressing, 10, 85 

W 

WRITE, 31, 79, 81, 57-58 
features of, 119-120,179-180 
format, 377 
Write Track 
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FutureWare, Inc. is pleased to offer the following two companion diskettes that 
will supplement the information found in Writing OS 12 Device Drivers : 

Assembly Language Sample Programs : Source code for sample 
programs included in text. Only $19.95. 

C Language Interface for Device Drivers and OS 12 Debugger : Com¬ 
plete support for writing Device Drivers in Microsoft C language, in¬ 
cludes source code for all routines. Only $49.95. 

Minimum Systems Requirements: IBM AT or compatible running OS/2. 


Use the following order form: 

PROGRAM ORDERED: PLEASE INDICATE MEDIA: PRICE: 

Assembly Language 5.25" Diskette_ $19.95 

Sample Programs 3.5" Diskette_ 

C Language Interface 5.25" Diskette_ $49.95 

for Device Drivers and 3.5" Diskette_ 

OS/2 Debugger 


All orders shipped UPS, either prepaid or COD. 

Shiping and Handling: UPS Ground ($5.00)/UPS Next Day ($10.00) $. 

NJ Residents add 6% sales tax: " $. 

Total enclosed: $. 

Name: _ 

Street: _ 

City: _State:_Zipcode:_ 


All programs sold in source form as is, without any implied warranty. Additional 
support is available for an hourly fee from FutureWare, Inc. Mail to: 

FutureWare, Inc. 

78 Temple Ave., Suite 15 
Hackensack, NJ 07601-6026 


MCI: FUTUREWARE 

Telephone: 201-343-2033/FAX: 201-343-3921 
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WRITING OS/2* DEVICE DRIVERS 

Raymond Westwater 


Device drivers—the thought intimidates the most dauntless developer. 
Device drivers for OS/2? You’ll need help, and it’s here! 


WRITING OS/2" DEVICE DRIVERS provides the applications developer with a one-stop 
reference for planning and implementing drivers in OS/2. The book starts with a comprehen¬ 
sive overview of the unique relationship between OS/2 and device drivers, discussing device 
drivers’ dependency on OS/2 software architecture and the underlying 80286 hardware. The 
reader is then introduced to the fundamentals of OS/2: process and thread management, file 
management, memory management, semaphore coordination, timer management, compat¬ 
ibility box support, and DOS variable access. 


Strategy packets, the exclusive means by which requests for data are forwarded from the 
OS/2 file manager to the device driver, are presented in a convenient format that defines 
field contents for LENGTH, UNIT, COMMAND, STATUS, RESERVED, and LINKAGE. 

Topics covered include: 

• Device Driver Structure 

• Device Driver Flow of Execution 

• Driver Development Strategies 

• I/O Packets 

• Device Helper Services. 

The coverage is comprehensive and leaves nothing to the imagination. 

Serious developers will immediately recognize that WRITING OS/2 DEVICE DRIVERS is 
of enormous value, saving many hours of painful “research” time. The critical information 
provided in this one volume cannot be obtained from any other reference and much of it is 
revealed to developers for the first time. 

Raymond Westwater is president of Futureware, Inc., a consulting firm specializing in OS/2 
systems and applications development. He is a Microsoft University-authorized training 
consultant for OS/2 device drivers. 
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